Restructure repo, add distinct_integers

Author: SuperAuguste

README.md

@@ -1,29 +1,29 @@
-# Zig Design Patterns
+# Zig Patterns
 
-- [Zig Design Patterns](#zig-design-patterns)
+- [Zig Patterns](#zig-patterns)
   - [About](#about)
-  - [Examples](#examples)
+  - [The Patterns](#the-patterns)
   - [License](#license)
 
 ## About
 
-This repository contains examples of common design patterns found in Zig's standard library and many community projects.
+This repository contains examples of common patterns found in Zig's standard library and many community projects.
 
 Note that copying (one of) these patterns verbatim into your project may not be useful; it's important to weigh the pros and cons of different patterns. If you come from another language, especially a non-systems one, you'll often find that the more unfamiliar ideas featured here may be more useful.
 
-For example, I've seldom used interface-like patterns when designing systems in Zig, despite using such patterns dozens of times a day at work writing TypeScript or Go.
+For example, I've seldom used interface-like patterns when designing systems in Zig, despite using such patterns dozens of times a day at my old job writing TypeScript or Go.
 
-## Examples
+## The Patterns
 
 All examples are annotated with comments including recommendations regarding when to use the patterns shown.
 
-| Example | How to run |
-| ----- | --- |
-| [`@fieldParentPtr`](src/field_parent_ptr.zig) | `zig build field_parent_ptr` |
-| [Inline Switch](src/inline_switch.zig) | `zig build inline_switch` |
-| [MultiArrayList](src/multi_array_list.zig) | `zig build multi_array_list` |
-| [Type Function](src/type_function.zig) | `zig build type_function` |
-| [Virtual Table](src/vtable.zig) | `zig build vtable` |
+Example tests can be run with `zig build [name_of_pattern]`. For example, to run the tests in `typing/type_function.zig`, run `zig build type_function`.
+
+Patterns are grouped into the following categories:
+- `data` - data layout and organization techniques
+- `typing` - `comptime`, runtime, or mixed `type` or type safety techniques
+
+Some patterns may belong in multiple categories; I've selected the most fitting one in my opinion.
 
 ## License
 

build.zig

@@ -1,11 +1,12 @@
 const std = @import("std");
 
 pub const examples = .{
-    .{ "field_parent_ptr", "src/field_parent_ptr.zig" },
-    .{ "inline_switch", "src/inline_switch.zig" },
-    .{ "multi_array_list", "src/multi_array_list.zig" },
-    .{ "type_function", "src/type_function.zig" },
-    .{ "vtable", "src/vtable.zig" },
+    .{ "field_parent_ptr", "src/typing/field_parent_ptr.zig" },
+    .{ "inline_switch", "src/typing/inline_switch.zig" },
+    .{ "multi_array_list", "src/data/multi_array_list.zig" },
+    .{ "type_function", "src/typing/type_function.zig" },
+    .{ "vtable", "src/typing/vtable.zig" },
+    .{ "distinct_integers", "src/typing/distinct_integers.zig" },
 };
 
 pub fn build(b: *std.Build) void {

src/multi_array_list.zig renamed to src/data/multi_array_list.zig

@@ -0,0 +1,47 @@
+//! When designing systems in Zig that take indices, it's important to
+//! ensure indices are not accidentally mixed up. For example, if I have
+//! a list `A` of length 10 and a list `B` of length 20, it is safe to
+//! access `A` with any number representing an index into `A`, and `B`
+//! with any number representing an index into `B`, but if we were to,
+//! for example, access `A` with a number representing an index into `B`,
+//! we could access garbage information or cause an out of bounds accesss.
+//! 
+//! A real world example I've run into while working on ZLS is accidentally
+//! swapping `TokenIndex`s and `Ast.Node.Index`s, which are both `= u32`.
+//! 
+//! ```zig
+//! pub fn accessANodeNotDistinct(node_index: u32) void {
+//!     // ...
+//! }
+//! 
+//! const token_index_not_a_node: u32 = 10;
+//! accessANodeNotDistinct(token_index_not_a_node);
+//! 
+//! // kabloom!
+//! ```
+//! 
+//! How can we avoid this? Distinct integers!
+
+const std = @import("std");
+
+pub const TokenIndex = enum(u32) {_};
+pub const NodeIndex = enum(u32) {_};
+
+pub fn lastToken() TokenIndex {
+    return @enumFromInt(0);
+}
+
+pub fn lastNode() NodeIndex {
+    return @enumFromInt(0);
+}
+
+pub fn accessANodeDistinct(node_index: NodeIndex) void {
+    // do node things
+    _ = node_index;
+}
+
+test {
+    accessANodeDistinct(lastNode());
+    // uncomment the line below this one and the program won't compile:
+    // accessANodeDistinct(lastToken());
+}

src/typing/distinct_integers.zig

@@ -24,7 +24,7 @@ pub const Cat = struct {
     favorite_food_brand: []const u8,
 
     pub fn sayHello(animal: *const Animal) void {
-        const cat = @fieldParentPtr(Cat, "animal", animal);
+        const cat: *const Cat = @fieldParentPtr("animal", animal);
         std.debug.print("Hi my name is {s} and I only eat {s}\n", .{ animal.name, cat.favorite_food_brand });
     }
 };
@@ -35,7 +35,7 @@ pub const Dog = struct {
     favorite_dog_toy: []const u8,
 
     pub fn sayHello(animal: *const Animal) void {
-        const dog = @fieldParentPtr(Dog, "animal", animal);
+        const dog: *const Dog = @fieldParentPtr("animal", animal);
         std.debug.print("Hi my name is {s} and my favorite dog toy is {s}\n", .{ animal.name, dog.favorite_dog_toy });
     }
 };