Something went wrong. Try again.
A CSV parsing library in Zig.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186//! csv_utils — a CSV parsing library for Zig.//!//! ## Quick start//!//! Streaming row-by-row with no allocation://! ```zig//! const csv = @import("csv_utils");//! var field_buf: [4096]u8 = undefined;//! var it = try csv.BoundedRowIterator(csv.default_max_fields)//! .init(reader, &field_buf, .{});//! while (try it.next()) |row| {//! for (row.fields) |field| { ... }//! }//! ```//!//! Full parse into memory://! ```zig//! var table = try csv.parseTable(reader, allocator);//! defer table.deinit();//! for (table.rows) |row| { ... }//! ```//!//! ## API layering//!//! ```//! HeaderTable ← lookup by (row, name); allocates//! └─ Table ← owned 2-D []const u8; allocates//! └─ HeaderIterator ← lookup by name per row; allocates//! └─ RowIterator family — three storage variants://! - RowIterator (allocating; grows)//! - BoundedRowIterator(N) (comptime stack)//! - FixedBufferRowIterator (caller buffer)//! └─ FieldIterator ← THE state machine//! └─ std.Io.Reader//! ```
const std = @import("std");const Io = std.Io;const Allocator = std.mem.Allocator;
// ── Re-exports ─────────────────────────────────────────────────────────────
pub const Dialect = @import("dialect.zig").Dialect;pub const Error = @import("error.zig").Error;
pub const FieldIterator = @import("field_iterator.zig").FieldIterator;
const row_iterator_mod = @import("row_iterator.zig");pub const Row = row_iterator_mod.Row;pub const RowIterator = row_iterator_mod.RowIterator;pub const BoundedRowIterator = row_iterator_mod.BoundedRowIterator;pub const FixedBufferRowIterator = row_iterator_mod.FixedBufferRowIterator;pub const default_max_fields = row_iterator_mod.default_max_fields;
pub const HeaderIterator = @import("header_iterator.zig").HeaderIterator;pub const Table = @import("table.zig").Table;pub const HeaderTable = @import("header_table.zig").HeaderTable;
pub const Writer = @import("writer.zig").Writer; // unimplemented; future feature
// ── Convenience wrappers using the default Dialect ─────────────────────────
/// Construct a no-allocator `BoundedRowIterator(default_max_fields)`/// over `reader` with the default dialect. The shortest-path entry/// point for "I just want to iterate rows".pub fn rows( reader: *Io.Reader, field_buf: []u8,) Error!BoundedRowIterator(default_max_fields) { return BoundedRowIterator(default_max_fields).init(reader, field_buf, .{});}
/// Construct an allocating `RowIterator` over `reader` with the/// default dialect. Use when row width may exceed/// `default_max_fields`.pub fn rowsAlloc( reader: *Io.Reader, field_buf: []u8, allocator: Allocator,) Error!RowIterator { return RowIterator.init(reader, field_buf, allocator, .{});}
/// Construct a `HeaderIterator` with default options.pub fn headerRows( reader: *Io.Reader, field_buf: []u8, allocator: Allocator,) Error!HeaderIterator { return HeaderIterator.init(reader, field_buf, allocator, .{});}
/// Parse the entire input into a `Table` with the default dialect.pub fn parseTable(reader: *Io.Reader, allocator: Allocator) Error!Table { return Table.parse(reader, allocator, .{});}
/// Parse the entire input into a `HeaderTable` with default options.pub fn parseHeaderTable(reader: *Io.Reader, allocator: Allocator) Error!HeaderTable { return HeaderTable.parse(reader, allocator, .{});}
test { // Pull in every submodule's test block when running `zig build test`. _ = @import("dialect.zig"); _ = @import("error.zig"); _ = @import("field_iterator.zig"); _ = @import("row_iterator.zig"); _ = @import("header_iterator.zig"); _ = @import("table.zig"); _ = @import("header_table.zig"); _ = @import("writer.zig");}
// ── Runnable examples (one per parser tier; N-12) ─────────────────────────
const testing = std.testing;
test "example: FieldIterator (lowest-level, no allocator)" { var reader = Io.Reader.fixed("a,b\n1,2\n"); var field_buf: [64]u8 = undefined; var it = try FieldIterator.init(&reader, &field_buf, .{}); var n_fields: usize = 0; while (try it.next()) |result| { _ = result.data; _ = result.end_of_row; n_fields += 1; } try testing.expectEqual(@as(usize, 4), n_fields);}
test "example: BoundedRowIterator (no allocator, comptime max columns)" { var reader = Io.Reader.fixed("a,b,c\n1,2,3\n"); var field_buf: [256]u8 = undefined; var it = try BoundedRowIterator(64).init(&reader, &field_buf, .{}); var n_rows: usize = 0; while (try it.next()) |row| { try testing.expectEqual(@as(usize, 3), row.count()); n_rows += 1; } try testing.expectEqual(@as(usize, 2), n_rows);}
test "example: RowIterator (allocating; unbounded row width)" { var reader = Io.Reader.fixed("a,b,c\n1,2,3\n"); var field_buf: [256]u8 = undefined; var it = try RowIterator.init(&reader, &field_buf, testing.allocator, .{}); defer it.deinit(); var n_rows: usize = 0; while (try it.next()) |row| { _ = row; n_rows += 1; } try testing.expectEqual(@as(usize, 2), n_rows);}
test "example: HeaderIterator (lookup by header name)" { var reader = Io.Reader.fixed("name,age\nAlice,30\nBob,25\n"); var field_buf: [256]u8 = undefined; var it = try HeaderIterator.init(&reader, &field_buf, testing.allocator, .{}); defer it.deinit();
const r1 = (try it.next()).?; try testing.expectEqualStrings("Alice", r1.get("name").?); try testing.expectEqualStrings("30", r1.get("age").?);
const r2 = (try it.next()).?; try testing.expectEqualStrings("Bob", r2.get("name").?);}
test "example: Table (full parse, random access by position)" { var reader = Io.Reader.fixed("a,b\n1,2\n3,4\n"); var t = try parseTable(&reader, testing.allocator); defer t.deinit(); try testing.expectEqual(@as(usize, 3), t.rows.len); try testing.expectEqualStrings("3", t.rows[2][0]);}
test "example: HeaderTable (full parse, random access by header)" { var reader = Io.Reader.fixed("name,score\nAlice,95\nBob,72\n"); var t = try parseHeaderTable(&reader, testing.allocator); defer t.deinit(); try testing.expectEqualStrings("95", t.get(0, "score").?); try testing.expectEqualStrings("Bob", t.get(1, "name").?);}