test:zig

guide/language/many-item-pointers.zig

@@ -0,0 +1,50 @@
+const expect = @import("std").testing.expect;
+const print = @import("std").debug.print;
+
+// Most programs need to keep track of buffers which don't have compile-time known lengths.
+// Many-item pointers are used for these. These act similarly to their single-item counterparts,
+// using the syntax `[*]T` instead of `*T`.
+
+// Here's a rundown of the differences between single and multi-item pointers.
+
+// Single-item pointers
+// * dereferenceable by `ptr.*`
+// * not indexable
+// * not supports arithmetic
+// * item size is any size, including unknown
+// * does not coerce from an array pointer
+
+// Multi-item pointers
+// * cannot be dereferenceable
+// * indexable by `ptr[0]`
+// * supports arithmetic
+// * item size is any size, including unknown
+// * coerces from an array pointer
+
+// Many-item pointers can have all of the same attributes, such as const, as single-item pointers.
+// In this example code, we've written a function that can take in a buffer of any length.
+// Notice how a single-item pointer to an array of bytes coerces into a many-item pointer of bytes.
+
+fn doubleAllManypointer(buffer: [*]u8, byte_count: usize) void {
+    var i: usize = 0;
+    while (i < byte_count) : (i += 1) buffer[i] *= 2;
+}
+
+test "many-item pointers" {
+    var buffer: [100]u8 = [_]u8{1} ** 100;
+    const buffer_ptr: *[100]u8 = &buffer;
+
+    const buffer_many_ptr: [*]u8 = buffer_ptr;
+    doubleAllManypointer(buffer_many_ptr, buffer.len);
+    for (buffer) |byte| try expect(byte == 2);
+
+    const first_elem_ptr: *u8 = &buffer_many_ptr[0];
+    const first_elem_ptr_2: *u8 = @ptrCast(buffer_many_ptr);
+    try expect(first_elem_ptr == first_elem_ptr_2);
+}
+
+// Think about what might happen if you passed that function the incorrect `byte_count`.
+// The programmer is expected to keep track of (or otherwise know) the length of these buffers.
+// It's worth noting that this function is effectively trusting us to pass us a valid length for the given buffer.
+// We can convert from a many-item pointer to a single-item pointer by either indexing an element and dereferencing that,
+// or by using `@ptrCast` to cast the pointer type. This is only valid when the buffer has a length of at least 1.