//! In-memory CSV table with header indexing. //! //! Like `Table`, but treats the first row as column headers and //! provides lookup of cells by header name. Supports configurable //! policies for duplicate header names and ragged-row handling. const std = @import("std"); const Io = std.Io; const Allocator = std.mem.Allocator; const Dialect = @import("dialect.zig").Dialect; const Error = @import("error.zig").Error; const row_iterator_mod = @import("row_iterator.zig"); const RowIterator = row_iterator_mod.RowIterator; /// In-memory CSV table with header indexing. Like `Table`, but the /// first row is treated as column headers and cells can be looked up /// by header name. Duplicate-header and ragged-row handling are /// configurable via `Options`. pub const HeaderTable = struct { /// Column headers (owned). headers: []const []const u8, /// Data rows, excluding the header row (owned). `rows[i][j]` is /// the j-th field of the i-th data row. rows: []const []const []const u8, /// Map from header name to column index. Built per the /// configured `DuplicatePolicy`. index: std.StringHashMapUnmanaged(usize), /// Owns every byte the table holds. arena: std.heap.ArenaAllocator, /// Policy for handling duplicate header names. The design /// document names this variant `error`; renamed to `err` here /// because `error` is a reserved Zig keyword. pub const DuplicatePolicy = enum { /// `parse` returns `error.DuplicateHeader` on the first /// duplicate. err, /// Lookups resolve to the first occurrence (subsequent /// occurrences are not indexed). first_wins, /// Lookups resolve to the last occurrence (later occurrences /// overwrite earlier ones in the index). last_wins, }; /// Policy for handling rows whose field count differs from the /// header row's. pub const WidthPolicy = enum { /// `parse` returns `error.RowWidthMismatch` on the first /// offending row. strict, /// Ragged rows are stored as-is; cell lookups for columns /// absent from a given row return null. permissive, }; /// Construction options. pub const Options = struct { dialect: Dialect = .{}, on_duplicate: DuplicatePolicy = .err, width: WidthPolicy = .permissive, }; /// Parse the entire contents of `reader`, treating the first row /// as headers. The caller must call `deinit()` to free all /// memory. On error, no memory is leaked. pub fn parse( reader: *Io.Reader, allocator: Allocator, opts: Options, ) Error!HeaderTable { try opts.dialect.validate(); var arena = std.heap.ArenaAllocator.init(allocator); errdefer arena.deinit(); const arena_alloc = arena.allocator(); const field_buf = try arena_alloc.alloc(u8, 4 * 1024); var row_iter = try RowIterator.init(reader, field_buf, arena_alloc, opts.dialect); // --- header row ---- const headers: []const []const u8 = blk: { const first = (try row_iter.next()) orelse { // Empty input: no headers, no rows. break :blk &[_][]const u8{}; }; const hdrs = try arena_alloc.alloc([]const u8, first.count()); for (first.fields, 0..) |f, i| { hdrs[i] = try arena_alloc.dupe(u8, f); } break :blk hdrs; }; // --- index ---- var index: std.StringHashMapUnmanaged(usize) = .empty; try index.ensureTotalCapacity(arena_alloc, @intCast(headers.len)); for (headers, 0..) |name, i| { const gop = try index.getOrPut(arena_alloc, name); if (gop.found_existing) { switch (opts.on_duplicate) { .err => return error.DuplicateHeader, .first_wins => {}, // keep existing .last_wins => gop.value_ptr.* = i, } } else { gop.value_ptr.* = i; } } // --- data rows ---- var rows: std.ArrayListUnmanaged([]const []const u8) = .empty; while (try row_iter.next()) |row| { if (opts.width == .strict and row.count() != headers.len) { return error.RowWidthMismatch; } const cells = try arena_alloc.alloc([]const u8, row.count()); for (row.fields, 0..) |f, i| { cells[i] = try arena_alloc.dupe(u8, f); } try rows.append(arena_alloc, cells); } const owned_rows = try rows.toOwnedSlice(arena_alloc); return .{ .headers = headers, .rows = owned_rows, .index = index, .arena = arena, }; } /// Frees all memory owned by the table. pub fn deinit(self: *HeaderTable) void { self.arena.deinit(); } /// Returns the index of the column with the given header name, /// or null if no such column exists. Honours the table's /// duplicate-header policy (e.g. under `first_wins`, returns the /// first occurrence's index). pub fn columnIndex(self: *const HeaderTable, name: []const u8) ?usize { return self.index.get(name); } /// Returns the value at `(row, name)`, or null if `row` is out /// of range, the header is unknown, or the row is shorter than /// the column's index. pub fn get(self: *const HeaderTable, row: usize, name: []const u8) ?[]const u8 { if (row >= self.rows.len) return null; const col = self.index.get(name) orelse return null; const r = self.rows[row]; return if (col < r.len) r[col] else null; } }; // ===== Tests ================================================================= const testing = std.testing; test "HeaderTable: happy path with columnIndex and get" { var reader = Io.Reader.fixed("name,age,city\nAlice,30,NYC\nBob,25,LA\n"); var t = try HeaderTable.parse(&reader, testing.allocator, .{}); defer t.deinit(); try testing.expectEqual(@as(?usize, 0), t.columnIndex("name")); try testing.expectEqual(@as(?usize, 1), t.columnIndex("age")); try testing.expectEqual(@as(?usize, 2), t.columnIndex("city")); try testing.expectEqual(@as(?usize, null), t.columnIndex("zzz")); try testing.expectEqualStrings("Alice", t.get(0, "name").?); try testing.expectEqualStrings("25", t.get(1, "age").?); try testing.expectEqualStrings("LA", t.get(1, "city").?); try testing.expectEqual(@as(?[]const u8, null), t.get(2, "name")); try testing.expectEqual(@as(?[]const u8, null), t.get(0, "zzz")); } test "HeaderTable: DuplicatePolicy.err returns DuplicateHeader" { var reader = Io.Reader.fixed("a,a\n1,2\n"); try testing.expectError( error.DuplicateHeader, HeaderTable.parse(&reader, testing.allocator, .{ .on_duplicate = .err }), ); } test "HeaderTable: DuplicatePolicy.first_wins resolves to first occurrence" { var reader = Io.Reader.fixed("a,a\n1,2\n"); var t = try HeaderTable.parse(&reader, testing.allocator, .{ .on_duplicate = .first_wins }); defer t.deinit(); try testing.expectEqualStrings("1", t.get(0, "a").?); } test "HeaderTable: DuplicatePolicy.last_wins resolves to last occurrence" { var reader = Io.Reader.fixed("a,a\n1,2\n"); var t = try HeaderTable.parse(&reader, testing.allocator, .{ .on_duplicate = .last_wins }); defer t.deinit(); try testing.expectEqualStrings("2", t.get(0, "a").?); } test "HeaderTable: WidthPolicy.permissive (default) accepts ragged rows" { var reader = Io.Reader.fixed("a,b\n1\n"); var t = try HeaderTable.parse(&reader, testing.allocator, .{}); defer t.deinit(); try testing.expectEqualStrings("1", t.get(0, "a").?); try testing.expectEqual(@as(?[]const u8, null), t.get(0, "b")); } test "HeaderTable: WidthPolicy.strict returns RowWidthMismatch on ragged row" { var reader = Io.Reader.fixed("a,b\n1\n"); try testing.expectError( error.RowWidthMismatch, HeaderTable.parse(&reader, testing.allocator, .{ .width = .strict }), ); } test "HeaderTable: empty input yields zero headers and zero rows" { var reader = Io.Reader.fixed(""); var t = try HeaderTable.parse(&reader, testing.allocator, .{}); defer t.deinit(); try testing.expectEqual(@as(usize, 0), t.headers.len); try testing.expectEqual(@as(usize, 0), t.rows.len); } test "HeaderTable: mid-parse error leaks nothing" { var reader = Io.Reader.fixed("a,b\n\"oops"); try testing.expectError( error.UnterminatedQuotedField, HeaderTable.parse(&reader, testing.allocator, .{}), ); }