# zig 0.15 patterns

notes from working with zig 0.15.2 in this codebase.

## ArrayListUnmanaged vs ArrayList

in zig 0.15, use `ArrayListUnmanaged` with explicit allocator per-method instead of `ArrayList.init(alloc)`:

```zig
// prefer this pattern
var results = std.ArrayListUnmanaged(MyType){};
try results.append(alloc, item);
defer results.deinit(alloc);
return results.toOwnedSlice(alloc);

// NOT this (old pattern)
var results = std.ArrayList(MyType).init(alloc);  // error: no member 'init'
```

this matches the pattern used throughout the codebase (see `db/*.zig`).

## pg.zig strict type checking

postgres driver (`pg.zig`) is strict about column types:

- `INTEGER` / `INT4` → must use `i32` via `row.getInt(col)`
- `BIGINT` / `INT8` → must use `i64` via `row.getBigInt(col)`

our backend.zig abstraction:
```zig
pub fn int(self: Row, col: usize) i64 {
    // for INTEGER columns
    return switch (self) {
        .sqlite => |r| r.int(col),
        .postgres => |r| r.getInt(col),  // returns i32, coerced to i64
    };
}

pub fn bigint(self: Row, col: usize) i64 {
    // for BIGINT columns
    return switch (self) {
        .sqlite => |r| r.int(col),
        .postgres => |r| r.getBigInt(col),  // returns i64
    };
}
```

## buffer allocation: stack first, heap fallback

for variable-size data, try stack buffer first, fall back to heap for large data:

```zig
var heap_buf: ?[]u8 = null;
defer if (heap_buf) |hb| alloc.free(hb);

const result = blk: {
    // try 64KB stack buffer first
    var stack_buf: [65536]u8 = undefined;
    break :blk doWork(&stack_buf, data) catch |err| {
        if (err == error.NoSpaceLeft and data.len > 60000) {
            // large data - allocate on heap
            heap_buf = try alloc.alloc(u8, data.len + 1024);
            break :blk try doWork(heap_buf.?, data);
        }
        return err;
    };
};
```

this avoids heap allocation for common cases while handling edge cases.

## function pointer types with slice parameters

when accepting buffers, use `[]u8` slice instead of pointer-to-array:

```zig
// flexible - works with stack and heap buffers
fn formatJson(buf: []u8, data: []const u8) ![]const u8 {
    return std.fmt.bufPrint(buf, ...);
}

// usage with stack buffer
var stack_buf: [65536]u8 = undefined;
_ = try formatJson(&stack_buf, data);

// usage with heap buffer
const heap_buf = try alloc.alloc(u8, size);
_ = try formatJson(heap_buf, data);
```