Something went wrong. Try again.
A CSV parsing library in Zig.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230//! 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, .{}), );}