//! Header-aware row iterator. //! //! Reads the first row of the input as column headers, then yields //! each subsequent row as a `HeaderRow` that supports both positional //! access and lookup by header name. //! //! Wraps an allocating `RowIterator`, inheriting unbounded row width. //! The caller's allocator is used for the wrapped iterator's row-slot //! storage and for owned copies of the header strings. 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; const Row = row_iterator_mod.Row; /// Header-aware row iterator. Reads the first row of the input as /// column headers, then yields each subsequent row as a `HeaderRow` /// that supports both positional access and lookup by header name. /// Wraps an allocating `RowIterator`, so row width is unbounded. pub const HeaderIterator = struct { row_iter: RowIterator, headers: [][]u8, // owned copies, freed on deinit allocator: Allocator, strict_width: bool, /// Sticky error after a strict-width violation. Once set, every /// subsequent `next()` returns this error. pending_error: ?Error, /// Construction options. pub const Options = struct { dialect: Dialect = .{}, /// If true, return `error.RowWidthMismatch` when any data row's /// field count differs from the header row's. Default: false /// (ragged rows accepted; missing fields surface as null /// `get` results). strict_width: bool = false, }; /// A single data row together with the header names. Supports /// positional access via `at(i)` and name-based lookup via /// `get(name)`. All slices borrow from the underlying iterator; /// they are invalidated by the next call to `next()`. pub const HeaderRow = struct { fields: []const []const u8, headers: []const []const u8, pub fn count(self: HeaderRow) usize { return self.fields.len; } pub fn at(self: HeaderRow, i: usize) ?[]const u8 { return if (i < self.fields.len) self.fields[i] else null; } /// Returns the value of the field whose column header equals /// `name`, or null if either no such header exists or the row /// has fewer fields than the matching column index. On /// duplicate headers, resolves to the first occurrence /// (first-wins; see requirements Story 3 #7). pub fn get(self: HeaderRow, name: []const u8) ?[]const u8 { for (self.headers, 0..) |h, i| { if (std.mem.eql(u8, h, name)) { return if (i < self.fields.len) self.fields[i] else null; } } return null; } }; /// Construct a header-aware iterator. The first row of `reader` /// is consumed immediately to populate the header list (copies /// owned by the iterator). If the input is empty (no header /// row), the resulting iterator has zero headers and its /// `next()` always returns null. pub fn init( reader: *Io.Reader, field_buf: []u8, allocator: Allocator, opts: Options, ) Error!HeaderIterator { var row_iter = try RowIterator.init(reader, field_buf, allocator, opts.dialect); errdefer row_iter.deinit(); var headers: std.ArrayListUnmanaged([]u8) = .empty; errdefer { for (headers.items) |h| allocator.free(h); headers.deinit(allocator); } if (try row_iter.next()) |row| { try headers.ensureTotalCapacity(allocator, row.count()); for (row.fields) |f| { const copy = try allocator.dupe(u8, f); headers.appendAssumeCapacity(copy); } } const owned = try headers.toOwnedSlice(allocator); return .{ .row_iter = row_iter, .headers = owned, .allocator = allocator, .strict_width = opts.strict_width, .pending_error = null, }; } /// Frees the header copies and tears down the wrapped row /// iterator. Does not free `field_buf` or the reader (caller- /// owned). pub fn deinit(self: *HeaderIterator) void { for (self.headers) |h| self.allocator.free(h); self.allocator.free(self.headers); self.row_iter.deinit(); } /// Yields the next data row, or null at end of input. /// /// Under `strict_width = true`, returns `error.RowWidthMismatch` /// (sticky) if the row's field count differs from the header /// row's. pub fn next(self: *HeaderIterator) Error!?HeaderRow { if (self.pending_error) |e| return e; const row = (try self.row_iter.next()) orelse return null; if (self.strict_width and row.count() != self.headers.len) { self.pending_error = error.RowWidthMismatch; return error.RowWidthMismatch; } return HeaderRow{ .fields = row.fields, .headers = self.headersConst(), }; } /// Returns the header names as `[]const []const u8`. Useful for /// callers that want to enumerate columns without a data row. pub fn headerNames(self: *const HeaderIterator) []const []const u8 { return self.headersConst(); } fn headersConst(self: *const HeaderIterator) []const []const u8 { // `[][]u8` decays to `[]const []const u8` via this cast. return @ptrCast(self.headers); } }; // ===== Tests ================================================================= const testing = std.testing; test "HeaderIterator: captures header row and yields data rows" { var reader = Io.Reader.fixed("name,age,city\nAlice,30,NYC\nBob,25,LA\n"); var field_buf: [256]u8 = undefined; var it = try HeaderIterator.init(&reader, &field_buf, testing.allocator, .{}); defer it.deinit(); try testing.expectEqual(@as(usize, 3), it.headerNames().len); try testing.expectEqualStrings("name", it.headerNames()[0]); try testing.expectEqualStrings("age", it.headerNames()[1]); try testing.expectEqualStrings("city", it.headerNames()[2]); const r1 = (try it.next()).?; try testing.expectEqualStrings("Alice", r1.get("name").?); try testing.expectEqualStrings("30", r1.get("age").?); try testing.expectEqualStrings("NYC", r1.get("city").?); const r2 = (try it.next()).?; try testing.expectEqualStrings("Bob", r2.get("name").?); try testing.expectEqualStrings("LA", r2.get("city").?); try testing.expectEqual(@as(?HeaderIterator.HeaderRow, null), try it.next()); } test "HeaderIterator: get returns null for unknown header name" { var reader = Io.Reader.fixed("a,b\n1,2\n"); var field_buf: [64]u8 = undefined; var it = try HeaderIterator.init(&reader, &field_buf, testing.allocator, .{}); defer it.deinit(); const r = (try it.next()).?; try testing.expectEqual(@as(?[]const u8, null), r.get("nonexistent")); } test "HeaderIterator: get returns null when row is shorter than header column" { var reader = Io.Reader.fixed("a,b,c\n1,2\n"); var field_buf: [64]u8 = undefined; var it = try HeaderIterator.init(&reader, &field_buf, testing.allocator, .{}); defer it.deinit(); const r = (try it.next()).?; try testing.expectEqualStrings("1", r.get("a").?); try testing.expectEqualStrings("2", r.get("b").?); try testing.expectEqual(@as(?[]const u8, null), r.get("c")); } test "HeaderIterator: duplicate headers resolve first-wins" { var reader = Io.Reader.fixed("a,a\nx,y\n"); var field_buf: [64]u8 = undefined; var it = try HeaderIterator.init(&reader, &field_buf, testing.allocator, .{}); defer it.deinit(); const r = (try it.next()).?; try testing.expectEqualStrings("x", r.get("a").?); } test "HeaderIterator: strict_width=false accepts ragged rows" { var reader = Io.Reader.fixed("a,b,c\n1\nx,y,z\n"); var field_buf: [64]u8 = undefined; var it = try HeaderIterator.init( &reader, &field_buf, testing.allocator, .{ .strict_width = false }, ); defer it.deinit(); const r1 = (try it.next()).?; try testing.expectEqualStrings("1", r1.get("a").?); try testing.expectEqual(@as(?[]const u8, null), r1.get("b")); const r2 = (try it.next()).?; try testing.expectEqualStrings("z", r2.get("c").?); } test "HeaderIterator: strict_width=true returns RowWidthMismatch (sticky)" { var reader = Io.Reader.fixed("a,b,c\n1,2\n"); var field_buf: [64]u8 = undefined; var it = try HeaderIterator.init( &reader, &field_buf, testing.allocator, .{ .strict_width = true }, ); defer it.deinit(); try testing.expectError(error.RowWidthMismatch, it.next()); try testing.expectError(error.RowWidthMismatch, it.next()); } test "HeaderIterator: empty input yields zero headers and zero rows" { var reader = Io.Reader.fixed(""); var field_buf: [64]u8 = undefined; var it = try HeaderIterator.init(&reader, &field_buf, testing.allocator, .{}); defer it.deinit(); try testing.expectEqual(@as(usize, 0), it.headerNames().len); try testing.expectEqual(@as(?HeaderIterator.HeaderRow, null), try it.next()); } test "HeaderIterator: deinit releases header copies (testing.allocator leak check)" { var reader = Io.Reader.fixed("alpha,beta,gamma\n1,2,3\n"); var field_buf: [128]u8 = undefined; var it = try HeaderIterator.init(&reader, &field_buf, testing.allocator, .{}); it.deinit(); // If this leaks, testing.allocator will fail the test. }