Something went wrong. Try again.
A CSV parsing library in Zig.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255//! 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.}