diegopacheco · September 2, 2023 06:10 · Jan 4, 2021 · Jan 3, 2021 · Jan 3, 2021 · Jan 3, 2021
diff --git a/test.md b/test.md
@@ -80,13 +80,16 @@ pub fn main() void {
 }
 ```
 
-You can explicitly choose to leave it undefined if it will get set later,
-but zig will error if you try to use it.
+You can explicitly choose to leave it undefined if it will get set later.  Zig will
+fill in a dummy value with 0XAA bytes to help detect errors in debug mode if you cause an
+error from accidentally using it in debug.
 
 ```zig
+const std = @import("std");
+
 pub fn main() void {
   var x: i32 = undefined;
-  foo(x); // error: use of undeclared identifier 'foo'
+  std.debug.print("undefined: {}\n", .{x});
 }
 ```
 

diff --git a/test.md b/test.md
@@ -734,19 +734,18 @@ pub fn main() !void {
     defer _ = gpa.deinit();
 
     var slice = try galloc.alloc(i32, 2);
+    // uncomment to remove memory leak warning
+    // defer galloc.free(slice);
+    
     var single = try galloc.create(i32);
+    // defer gallo.destroy(single);
 
     slice[0] = 47;
     slice[1] = 48;
     single.* = 49;
 
     std.debug.print("slice: [{}, {}]\n", .{slice[0], slice[1]});
     std.debug.print("single: {}\n", .{single.*});
-    
-    // oops! we forgot to free that memory.
-    // uncomment these to remove memory leak warning:
-    // galloc.free(slice);
-    // galloc.destroy(single);
 }
 ```
 

diff --git a/test.md b/test.md
@@ -251,9 +251,10 @@ pub fn main() void {
 ```
 
 By the way, that thing we've been passing into the std.debug.print's second parameter
-is an *anonymous struct with number fields*.  At *compile time*, the contents and types 
-of the parameters are analyzed and matched up to the (compile time) format string that 
-you provided, and that's how zig knows how to make the contents of the print pretty.
+is a tuple.  Without going into too much detail, it's an *anonymous struct with number fields*.  
+At *compile time*, `std.debug.print` figures out types of the parameters in that tuple and 
+generates a version of itself tuned for the parameters string that you provided, and that's 
+how zig knows how to make the contents of the print pretty.
 
 ```zig
 const std = @import("std");

diff --git a/test.md b/test.md
@@ -691,10 +691,10 @@ From these concepts you can build very powerful generics!
 Zig gives you many ways to interact with the heap, and usually requires you to be
 explicit about your choices.  They all follow the same pattern:
 
-1. Create an AllocatorFactory struct.
-2. Retrieve the `std.mem.Allocator` struct creacted by the AllocatorFactory.
+1. Create an Allocator factory struct.
+2. Retrieve the `std.mem.Allocator` struct creacted by the Allocator factory.
 3. Use the alloc/free and create/destroy functions to manipulate the heap.
-4. (optional) deinit the AllocatorFactor.
+4. (optional) deinit the Allocator factory.
 
 Whew!  That sounds like a lot.  But
 - this is to discourage you from using the heap.

diff --git a/test.md b/test.md
@@ -699,7 +699,8 @@ explicit about your choices.  They all follow the same pattern:
 Whew!  That sounds like a lot.  But
 - this is to discourage you from using the heap.
 - it makes anything which calls the heap (which are fundamentally failable) obvious.
-- by being unopinionated, you can carefully tune your tradeoffs *without having to rewrite the standard library*.
+- by being unopinionated, you can carefully tune your tradeoffs and use standard datastructures
+  *without having to rewrite the standard library*.
 - you can run an extremely safe allocator in your tests and swap it out for a different
   allocator in release/prod.
 

diff --git a/test.md b/test.md
@@ -686,6 +686,68 @@ pub fn main() void {
 
 From these concepts you can build very powerful generics!
 
+## The HEAP
+
+Zig gives you many ways to interact with the heap, and usually requires you to be
+explicit about your choices.  They all follow the same pattern:
+
+1. Create an AllocatorFactory struct.
+2. Retrieve the `std.mem.Allocator` struct creacted by the AllocatorFactory.
+3. Use the alloc/free and create/destroy functions to manipulate the heap.
+4. (optional) deinit the AllocatorFactor.
+
+Whew!  That sounds like a lot.  But
+- this is to discourage you from using the heap.
+- it makes anything which calls the heap (which are fundamentally failable) obvious.
+- by being unopinionated, you can carefully tune your tradeoffs *without having to rewrite the standard library*.
+- you can run an extremely safe allocator in your tests and swap it out for a different
+  allocator in release/prod.
+
+Ok.  But **you can still be lazy**.  Do you miss just using jemalloc everywhere?  
+Just pick a global allocator and use that everywhere (being aware that some allocators are 
+threadsafe and some allocators are not)!  Please don't do this if you are writing
+a general purpose library.
+
+In this example we'll use the std.heap.GeneralPurposeAllocator factory to create an allocator
+with a bunch of bells and whistles (including leak detection) and see how this comes together.
+
+One last thing, this uses the `defer` keyword, which is a lot like go's defer keyword!  There's also
+an `errdefer` keyword, but to learn more about that check the Zig docs (linked below).
+
+```zig
+const std = @import("std");
+
+// factory type
+const Gpa = std.heap.GeneralPurposeAllocator(.{});
+
+pub fn main() !void {
+    // instantiates the factory
+    var gpa = Gpa{};
+    
+    // retrieves the created allocator.
+    var galloc = &gpa.allocator;
+    
+    // scopes the lifetime of the allocator to this function and
+    // performs cleanup; 
+    defer _ = gpa.deinit();
+
+    var slice = try galloc.alloc(i32, 2);
+    var single = try galloc.create(i32);
+
+    slice[0] = 47;
+    slice[1] = 48;
+    single.* = 49;
+
+    std.debug.print("slice: [{}, {}]\n", .{slice[0], slice[1]});
+    std.debug.print("single: {}\n", .{single.*});
+    
+    // oops! we forgot to free that memory.
+    // uncomment these to remove memory leak warning:
+    // galloc.free(slice);
+    // galloc.destroy(single);
+}
+```
+
 ## Coda
 
 That's it!  Now you know a fairly decent chunk of zig.  Some (pretty important) things I didn't cover include:

diff --git a/test.md b/test.md
@@ -568,7 +568,7 @@ in one shot with the `.` operator.  Note this only works with one level of
 indirection, so if you have a pointer to a pointer, you must dereference the
 outer pointer first.
 
-```
+```zig
 const std = @import("std");
 
 const MyStruct = struct {

diff --git a/test.md b/test.md
@@ -540,6 +540,93 @@ pub fn main() void {
 }
 ```
 
+## Pointers
+
+Pointer types are declared by prepending `*` to the front of the type.  No spiral declarations
+like C!  They are dereferenced, with the `.*` field:
+
+```zig
+const std = @import("std");
+
+pub fn printer(value: *i32) void {
+    std.debug.print("pointer: {}\n", .{value});
+    std.debug.print("value: {}\n", .{value.*});
+}
+
+pub fn main() void {
+    var value: i32 = 47;
+    printer(&value);
+}
+```
+
+Note: 
+- in Zig, pointers need to be aligned correctly with the alignment of the
+  value it's pointing to.
+
+For structs, similar to Java, you can dereference the pointer and get the field
+in one shot with the `.` operator.  Note this only works with one level of
+indirection, so if you have a pointer to a pointer, you must dereference the
+outer pointer first.
+
+```
+const std = @import("std");
+
+const MyStruct = struct {
+    value: i32
+};
+
+pub fn printer(s: *MyStruct) void {
+    std.debug.print("value: {}\n", .{s.value});
+}
+
+pub fn main() void {
+    var value = MyStruct{.value = 47};
+    printer(&value);
+}
+```
+
+Zig allows any type (not just pointers) to be nullable, but note that they are unions of the base type
+and the special value `null`.  To access the unwrapped optional type, use the `.?` field:
+
+```zig
+const std = @import("std");
+
+pub fn main() void {
+    var value: i32 = 47;
+    var vptr: ?*i32 = &value;
+    var throwaway1: ?*i32 = null;
+    var throwaway2: *i32 = null; // error: expected type '*i32', found '(null)'
+
+    std.debug.print("value: {}\n", .{vptr.*}); // error: attempt to dereference non-pointer type
+    std.debug.print("value: {}\n", .{vptr.?.*});
+}
+```
+Note:
+- when you use pointers from C ABI functions they are automatically converted to nullable pointers.
+
+Another way of obtaining the unwrapped optional pointer is with the `if` statement:
+
+```zig
+const std = @import("std");
+
+fn nullChoice(value: ?*i32) void {
+    if (value) | v | {
+        std.debug.print("value: {}\n", .{v.*});
+    } else {
+        std.debug.print("null!\n", .{});
+    }
+}
+
+pub fn main() void {
+    var value: i32 = 47;
+    var vptr1: ?*i32 = &value;
+    var vptr2: ?*i32 = null;
+
+    nullChoice(vptr1);
+    nullChoice(vptr2);
+}
+```
+
 ## A taste of metaprogramming
 
 Zig's metaprogramming is driven by a few basic concepts:
@@ -603,7 +690,6 @@ From these concepts you can build very powerful generics!
 
 That's it!  Now you know a fairly decent chunk of zig.  Some (pretty important) things I didn't cover include:
 
-- pointers
 - tests!  Dear god please write tests.  Zig makes it easy to do it.
 - the standard library
   - the memory model (somewhat uniquely, zig is aggressively unopinionated about allocators)

diff --git a/test.md b/test.md
@@ -30,7 +30,9 @@ pub fn main() void {
     std.debug.print("hello world!\n", .{});
 }
 ```
-I'll explain the odd print calling convention later, in the Arrays section.
+
+Note:
+- I'll explain the funny second parameter in the print statement, later in the structs section.
 
 `var` declares a variable, in most cases you should declare the variable type.
 
@@ -247,6 +249,20 @@ pub fn main() void {
     obj.print();
 }
 ```
+
+By the way, that thing we've been passing into the std.debug.print's second parameter
+is an *anonymous struct with number fields*.  At *compile time*, the contents and types 
+of the parameters are analyzed and matched up to the (compile time) format string that 
+you provided, and that's how zig knows how to make the contents of the print pretty.
+
+```zig
+const std = @import("std");
+
+pub fn main() void {
+    std.debug.print("{}\n", .{1, 2}); #  error: Unused arguments
+}
+```
+
 ## Enums
 
 Enums are declared by assigning the group of enums as a type using the
@@ -326,19 +342,6 @@ pub fn main() void {
 }
 ```
 
-By the way, that thing we've been passing into the std.debug.print's second parameter
-an *anonymous array*.  at compile time, the contents and types of the parameters are
-analyzed and matched up to the (compile time) format string that you provided, and that's
-how zig knows how to make the contents of the print pretty.
-
-```zig
-const std = @import("std");
-
-pub fn main() void {
-    std.debug.print("{}\n", .{1, 2}); #  error: Unused arguments
-}
-```
-
 string literals are null-terminated utf-8 encoded arrays of `const u8` bytes.  
 Unicode characters are only allowed in string literals and comments.
 

diff --git a/test.md b/test.md
@@ -546,7 +546,8 @@ Zig's metaprogramming is driven by a few basic concepts:
 - the zig standard library gives you tools to perform compile-time
   reflection.
 
-Here's an example of multiple dispatch:
+Here's an example of multiple dispatch (though you have already seen this in action with 
+`std.debug.print`, perhaps now you can imagine how it's implemented:
 
 ```zig
 const std = @import("std");

diff --git a/test.md b/test.md
@@ -30,6 +30,7 @@ pub fn main() void {
     std.debug.print("hello world!\n", .{});
 }
 ```
+I'll explain the odd print calling convention later, in the Arrays section.
 
 `var` declares a variable, in most cases you should declare the variable type.
 

diff --git a/test.md b/test.md
@@ -21,7 +21,7 @@ pub fn main() void {}
 You can import from the standard library by using the `@import` builtin and
 assigning the namespace to a const value.  Almost everything in zig must be
 explicitly assigned its identifier.  You can also import other zig files this
-way, and C files in a similar fashion.
+way, and C files in a similar fashion with `@cImport`.
 
 ```zig
 const std = @import("std");
@@ -325,6 +325,19 @@ pub fn main() void {
 }
 ```
 
+By the way, that thing we've been passing into the std.debug.print's second parameter
+an *anonymous array*.  at compile time, the contents and types of the parameters are
+analyzed and matched up to the (compile time) format string that you provided, and that's
+how zig knows how to make the contents of the print pretty.
+
+```zig
+const std = @import("std");
+
+pub fn main() void {
+    std.debug.print("{}\n", .{1, 2}); #  error: Unused arguments
+}
+```
+
 string literals are null-terminated utf-8 encoded arrays of `const u8` bytes.  
 Unicode characters are only allowed in string literals and comments.
 

diff --git a/test.md b/test.md
@@ -586,9 +586,10 @@ From these concepts you can build very powerful generics!
 That's it!  Now you know a fairly decent chunk of zig.  Some (pretty important) things I didn't cover include:
 
 - pointers
-- async
+- tests!  Dear god please write tests.  Zig makes it easy to do it.
 - the standard library
   - the memory model (somewhat uniquely, zig is aggressively unopinionated about allocators)
+- async
 - cross-compilation
 - build.zig
 

diff --git a/test.md b/test.md
@@ -224,11 +224,11 @@ pub fn main() void {
 }
 ```
 
-You can drop functions into an struct to make it work like a C++-style object.
+You can drop functions into an struct to make it work like a OOP-style object.
 There is syntactic sugar where if you make the functions' first parameter be
 a pointer to the object, it can be called "Object-style", similar to how Python
 has the self-parametered member functions.  The typical convention is to make this
-explicit by calling the variable self.
+obvious by calling the variable self.
 
 ```zig
 const std = @import("std");

diff --git a/test.md b/test.md
@@ -224,6 +224,28 @@ pub fn main() void {
 }
 ```
 
+You can drop functions into an struct to make it work like a C++-style object.
+There is syntactic sugar where if you make the functions' first parameter be
+a pointer to the object, it can be called "Object-style", similar to how Python
+has the self-parametered member functions.  The typical convention is to make this
+explicit by calling the variable self.
+
+```zig
+const std = @import("std");
+
+const LikeAnObject = struct{
+    value: i32,
+
+    fn print(self: *LikeAnObject) void {
+        std.debug.print("value: {}\n", .{self.value});
+    }
+};
+
+pub fn main() void {
+    var obj = LikeAnObject{.value = 47};
+    obj.print();
+}
+```
 ## Enums
 
 Enums are declared by assigning the group of enums as a type using the

diff --git a/test.md b/test.md
@@ -20,7 +20,8 @@ pub fn main() void {}
 
 You can import from the standard library by using the `@import` builtin and
 assigning the namespace to a const value.  Almost everything in zig must be
-explicitly assigned its identifier.
+explicitly assigned its identifier.  You can also import other zig files this
+way, and C files in a similar fashion.
 
 ```zig
 const std = @import("std");
@@ -562,6 +563,7 @@ From these concepts you can build very powerful generics!
 
 That's it!  Now you know a fairly decent chunk of zig.  Some (pretty important) things I didn't cover include:
 
+- pointers
 - async
 - the standard library
   - the memory model (somewhat uniquely, zig is aggressively unopinionated about allocators)

diff --git a/test.md b/test.md
@@ -564,7 +564,7 @@ That's it!  Now you know a fairly decent chunk of zig.  Some (pretty important)
 
 - async
 - the standard library
-  - the memory model (zig is pretty aggressively unopinionated about memory)
+  - the memory model (somewhat uniquely, zig is aggressively unopinionated about allocators)
 - cross-compilation
 - build.zig
 

diff --git a/test.md b/test.md
@@ -560,7 +560,13 @@ From these concepts you can build very powerful generics!
 
 ## Coda
 
-That's it!  Now you know a fairly decent chunk of zig.
+That's it!  Now you know a fairly decent chunk of zig.  Some (pretty important) things I didn't cover include:
+
+- async
+- the standard library
+  - the memory model (zig is pretty aggressively unopinionated about memory)
+- cross-compilation
+- build.zig
 
 For more details, check the latest documentation:
 https://ziglang.org/documentation/master/

diff --git a/test.md b/test.md
@@ -502,7 +502,7 @@ pub fn main() void {
 
 ## A taste of metaprogramming
 
-Zig's metaprogramming is driven by two basic concepts:
+Zig's metaprogramming is driven by a few basic concepts:
 - Types are valid values at compile-time
 - most runtime code will also work at compile-time.
 - struct field evaluation is compile-time duck-typed.

diff --git a/test.md b/test.md
@@ -505,7 +505,7 @@ pub fn main() void {
 Zig's metaprogramming is driven by two basic concepts:
 - Types are valid values at compile-time
 - most runtime code will also work at compile-time.
-- anonymous struct coercion is compile-time duck-typed.
+- struct field evaluation is compile-time duck-typed.
 - the zig standard library gives you tools to perform compile-time
   reflection.
 
@@ -552,7 +552,7 @@ pub fn main() void {
     var vf = V2f64{.x = 47.0, .y = 47.0};
     
     std.debug.print("i64 vector: {}\n", .{vi});
-    std.debug.print("i32 vector: {}\n", .{vf});
+    std.debug.print("f64 vector: {}\n", .{vf});
 }
 ```
 

diff --git a/test.md b/test.md
@@ -1,5 +1,7 @@
 # A half-hour to learn Zig
 
+This is inspired by https://fasterthanli.me/blog/2020/a-half-hour-to-learn-rust/
+
 ## Basics
 
 the command `zig run my_code.zig` will compile and immediately run your Zig

diff --git a/test.md b/test.md
@@ -108,8 +108,9 @@ pub fn main() void {
 
 ## Functions
 
-Here's a function (`foo`) that returns nothing.  You call functions just
-as you would in most programming languages:
+Here's a function (`foo`) that returns nothing.  The `pub` keyword means that the
+function is exportable from the current scope, which is why main must be `pub`.  You 
+call functions just as you would in most programming languages:
 
 ```zig
 const std = @import("std");
@@ -463,7 +464,7 @@ pub fn main() !void {
     // try won't get activated here.
     std.debug.print("foo: {}\n", .{try foo(47)});
 
-    // this will ultimately cause main to crash.
+    // this will ultimately cause main to print an error trace and return nonzero
     _ = try foo(42);
 }
 ```

diff --git a/test.md b/test.md
@@ -266,6 +266,7 @@ pub fn main() void {
 
     var invalid = array[4]; // error: index 4 outside array of size 3.
     std.debug.print("array[0]: {}\n", .{array[0]});
+    std.debug.print("length: {}\n", .{array.len});
 }
 ```
 

diff --git a/test.md b/test.md
@@ -530,7 +530,7 @@ pub fn main() void {
 
 Here's an example of generic types:
 
-```
+```zig
 const std = @import("std");
 
 fn Vec2Of(comptime T: type) type {

diff --git a/test.md b/test.md
@@ -501,6 +501,7 @@ pub fn main() void {
 Zig's metaprogramming is driven by two basic concepts:
 - Types are valid values at compile-time
 - most runtime code will also work at compile-time.
+- anonymous struct coercion is compile-time duck-typed.
 - the zig standard library gives you tools to perform compile-time
   reflection.
 

diff --git a/test.md b/test.md
@@ -504,6 +504,8 @@ Zig's metaprogramming is driven by two basic concepts:
 - the zig standard library gives you tools to perform compile-time
   reflection.
 
+Here's an example of multiple dispatch:
+
 ```zig
 const std = @import("std");
 
@@ -525,6 +527,30 @@ pub fn main() void {
 }
 ```
 
+Here's an example of generic types:
+
+```
+const std = @import("std");
+
+fn Vec2Of(comptime T: type) type {
+    return struct{
+        x: T,
+        y: T
+    };
+}
+
+const V2i64 = Vec2Of(i64);
+const V2f64 = Vec2Of(f64);
+
+pub fn main() void {
+    var vi = V2i64{.x = 47, .y = 47};
+    var vf = V2f64{.x = 47.0, .y = 47.0};
+    
+    std.debug.print("i64 vector: {}\n", .{vi});
+    std.debug.print("i32 vector: {}\n", .{vf});
+}
+```
+
 From these concepts you can build very powerful generics!
 
 ## Coda

diff --git a/test.md b/test.md
@@ -526,3 +526,13 @@ pub fn main() void {
 ```
 
 From these concepts you can build very powerful generics!
+
+## Coda
+
+That's it!  Now you know a fairly decent chunk of zig.
+
+For more details, check the latest documentation:
+https://ziglang.org/documentation/master/
+
+or for a less half-baked tutorial, go to:
+https://ziglearn.org/
diff --git a/test.md b/test.md
@@ -18,7 +18,7 @@ pub fn main() void {}
 
 You can import from the standard library by using the `@import` builtin and
 assigning the namespace to a const value.  Almost everything in zig must be
-explicitly assigned its values.
+explicitly assigned its identifier.
 
 ```zig
 const std = @import("std");

diff --git a/test.md b/test.md
@@ -191,7 +191,7 @@ const std = @import("std");
 const Vec2 = struct{
     x: f64,
     y: f64
-}q
+};
 
 pub fn main() void {
     var v = Vec2{.y = 1.0, .x = 2.0};

diff --git a/test.md b/test.md
@@ -9,7 +9,7 @@ with)
 
 You'll want to declare a main() function to get started running code.
 
-This program does nothing:
+This program does almost nothing:
 
 ```zig
 // comments look like this and go to the end of the line
No results found