Update README and add MultiArrayList example

Author: SuperAuguste

README.md

@@ -7,7 +7,11 @@
 
 ## About
 
-This repository contains examples of common design patterns found in Zig's standard library and many community projects. I hope that these examples will help people new to the language gain an understanding of the many ways one can structure their programs in Zig, as well as why Zig does not prescribe a certain way to do "interfaces."
+This repository contains examples of common design 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.
 
 ## Examples
 
@@ -17,6 +21,7 @@ All examples are annotated with comments including recommendations regarding whe
 | ----- | --- |
 | [`@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` |
 

build.zig

@@ -3,6 +3,7 @@ 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" },
 };

src/multi_array_list.zig

@@ -0,0 +1,70 @@
+//! Let's say that we want to store a list of `struct {a: u8, b: u16}`s.
+//!
+//! We could use a normal ArrayList; we'd call this an Array of Structs (AoS) design,
+//! though in Zig "Slice of Structs" would be a more correct name, because we'd be
+//! storing a list where each entry in the list stores the whole struct contiguously.
+//!
+//! Alternatively, we could use MultiArrayList, where the list is split into
+//! `Struct.fields.len` segments, each storing all the values of a certain field
+//! contiguously. We'd call this a Struct of Arrays (SoA) design, which is
+//! also a misnomer when applied to Zig. :^)
+//!
+//! This is a little odd to wrap one's head around at first, so here's a diagram
+//! of how each design looks in memory with the example struct mentioned above:
+//!
+//! ArrayList (AoS):      { {aaaaaaaabbbbbbbbbbbbbbbb} {aaaaaaaabbbbbbbbbbbbbbbb} {aaaaaaaabbbbbbbbbbbbbbbb} }
+//! MultiArrayList (SoA): { {aaaaaaaa} {aaaaaaaa} {aaaaaaaa} {bbbbbbbbbbbbbbbb} {bbbbbbbbbbbbbbbb} {bbbbbbbbbbbbbbbb} }
+//!
+//! Both example lists show three entries and each letter represents a bit of memory for
+//! that field. Note that this diagram is simplified, and that we do not represent
+//! any padding that may be introduced by the compiler.
+//!
+//! When to use:
+//! - You only access certain fields most of the time, and loading
+//!   the entire struct would be a waste
+//! - You want to help the compiler autovectorize / perform some
+//!   manual vectorization using Zig's SIMD features
+//!
+//! When not to use:
+//! - If you're always accessing every field in your list entries,
+//!   then you won't find much use in MultiArrayLists
+
+const std = @import("std");
+
+pub const Player = struct {
+    name: []const u8,
+    health: u16,
+};
+
+const PlayerList = std.MultiArrayList(Player);
+
+test {
+    const allocator = std.testing.allocator;
+
+    var players = PlayerList{};
+    defer players.deinit(allocator);
+
+    try players.append(allocator, .{ .name = "Auguste", .health = 100 });
+    try players.append(allocator, .{ .name = "Techatrix", .health = 125 });
+    try players.append(allocator, .{ .name = "ZLS Premium User", .health = 50_000 });
+
+    // We're about to call `.items(...)` a bunch,
+    // so we can save some performance by
+    // calling `.slice()` and calling `.items(...)`
+    // on that instead.
+    var slice = players.slice();
+
+    // I just want to increase every player's health!
+    // This pattern allows LLVM to easily autovectorize
+    // this modification code; I challenge you to look
+    // at this in Compiler Explorer! :)
+    for (slice.items(.health)) |*health| {
+        health.* += 10;
+    }
+
+    // Let's access both fields and see where our players'
+    // health is at now!
+    for (slice.items(.name), slice.items(.health)) |name, health| {
+        std.debug.print("{s} has {d} health!\n", .{ name, health });
+    }
+}