Esc

Csv

moduleextensionSource
  • macOS: Everything works on macOS
  • Linux: Everything works on Linux
  • Windows: Everything works on Windows
  • Wasm: Everything works on Wasm
·since 0.36.1

#import "Extensions/Csv";

Reads and writes CSV with explicit limits. A record read from a Csv_Reader is borrowed until the next call; copy it to keep it. A reader made with a row type (csv_reader(User, ...)) decodes each record into that struct; its rows own their strings unless borrow is set.

Example↗
#import "Extensions/Csv";

r := csv_reader(cast([] u8) "name,age\nada,36\n", .{ header = true });
defer csv_reader_free(*r);
fields, present, error := csv_next(*r);
assert(present && error.kind == .NONE);
assert(fields[0] == "ada" && fields[1] == "36");

User :: struct {
    name: string;
    age: int;
}
typed := csv_reader(User, cast([] u8) "name,age\nada,36\n", .{ header = true });
defer csv_reader_free(*typed);
for user: typed {
    defer csv_row_free(*user);
    assert(user.name == "ada" && user.age == 36);
}
assert(typed.error.kind == .NONE);

Procedures#

General#

csv_reader4 overloadssince 0.36.1Source
(input: [] u8, options := Csv_Options.{}) -> Csv_Reader
(source: Csv_Source, options := Csv_Options.{}) -> Csv_Reader
($Row: Type, input: [] u8, options := Csv_Options.{}) -> Csv_Reader(Row)
($Row: Type, source: Csv_Source, options := Csv_Options.{}) -> Csv_Reader(Row)

Creates a reader of records over input, which it borrows; release it with csv_reader_free. Example:

r := csv_reader(cast([] u8) "one,two\n", .{ header = true });
defer csv_reader_free(*r);
↗
csv_next2 overloadssince 0.36.1Source
(r: *Csv_Reader(void)) -> ([] string, bool, Csv_Error)
(r: *Csv_Reader($Row)) -> (Row, bool, Csv_Error)

Returns the next record as borrowed fields, or false with .NONE at the end of the input. With a header the first record is consumed as the column names. Example:

#import "Extensions/Csv";

r := csv_reader(cast([] u8) "a,b\n1,2\n");
defer csv_reader_free(*r);
fields, present, error := csv_next(*r);
assert(present && fields.count == 2 && fields[1] == "b");
↗
(r: *Csv_Reader($Row), body: Code, flags: For_Flags)

Iterates a reader: for row: reader runs the body per record (a [] string or a Row) until the input ends or a record fails, and reader.error then says which. A typed row is released by the body. Example:

#import "Extensions/Csv";

User :: struct {
    name: string;
    age: int;
}

reader := csv_reader(User, cast([] u8) "name,age\nada,36\nbob,x\n", .{ header = true });
defer csv_reader_free(*reader);
count := 0;
for user, index: reader {
    defer csv_row_free(*user);
    assert(user.name == "ada" && index == 0);
    count += 1;
}
assert(count == 1 && reader.error.kind == .TYPE);
↗
(fields: [] string) -> [] string

Copies a borrowed record into independently owned fields. Example: owned := csv_record_copy(fields); csv_record_free(owned).

(fields: [] string)

Releases a copied record, including its field strings. Example: csv_record_free(owned).

(r: *Csv_Reader($Row))

Releases reader storage; input and source state stay caller-owned. Works for both kinds of reader. Example: csv_reader_free(*reader).

(out: *String_Builder, fields: [] string, options := Csv_Options.{}) -> Csv_Error

Appends one record atomically after checking the configured field and record limits. Example: error := csv_write_record(*builder, string.["a,b", "two"]).

Typed#

csv_row_free2 overloadssince 0.36.1Source
(value: *$T)
(reader: *Csv_Reader($Row), value: *Row)

Releases strings and optional pointers owned by a typed row; resets decoded fields. Not for a row read with Csv_Options.borrow: use the reader form below. Example: csv_row_free(*row).

(out: *String_Builder, rows: [] $T, options := Csv_Options.{}) -> Csv_Error

Writes a struct array with a header, honoring @csv(name=...) and @csv(skip). Example: error := csv_write_rows(*builder, users).

Types#

Csv_Optionsstructsince 0.36.1Source

How a CSV document is read and written.

Csv_Options :: struct {
    delimiter: u8 = #char ",";
    quote: u8 = #char "\"";
    header: bool;
    trim: bool;
    lax_quotes: bool;
    require_equal_width: bool;
    max_field_bytes: int = 1 << 20;
    max_fields: int = 16384;
    max_record_bytes: int = 16 << 20;
    line_ending := Csv_Line_Ending.CRLF;

    borrow: bool;
}
Csv_Error_Kindenumsince 0.36.1Source

Why reading, writing or decoding a CSV failed.

Csv_Error_Kind :: enum {
    NONE;
    OPTIONS;
    QUOTE;
    FIELD_LIMIT;
    FIELD_COUNT;
    RECORD_LIMIT;
    WIDTH;
    SOURCE;
    TYPE;
    HEADER;
}
Csv_Errorstructsince 0.36.1Source

The outcome of a CSV operation; kind is .NONE on success. Positions are 1-based, offset is a byte offset.

Csv_Error :: struct {
    kind: Csv_Error_Kind;
    message: string;
    line: int;
    column: int;
    offset: int;
    column_name: string;
}
Csv_Sourcetypesince 0.36.1Source
:: Pieces.Byte_Source

A CSV document that arrives in pieces: fill puts the next piece in buffer and returns how many bytes it wrote (0 at the end), or a non-empty string when the source failed. Json_Source is the same type.

Csv_Corestructsince 0.36.1Source

The parser state every reader shares: the input window, the position, the header and the column mapping. Csv_Reader wraps it; the fields are internal.

Csv_Core :: struct {
    source: Csv_Source;
    window: [] u8;
    eof: bool;
    options: Csv_Options;
    input: [] u8;
    position: int;
    offset: int;
    line: int = 1;
    line_start: int;
    previous_cr: bool;
    started: bool;
    header_ready: bool;
    header: [] string;
    header_index: Hash_Map.Map(string, int);
    columns: [..] int;
    bound: bool;
    allocator: Allocator;
    width: int = -1;
    buffer: [..] u8;
    cells: [..] Csv_Cell;
    fields: [..] string;
    stops: [256] u8;
    marks: Csv_Marks;
    block_base: int = -1;
    block_unquoted: u64;
    block_quoted: u64;
    decoded: [..] Csv_Decoded;
    bytewise: bool;
    source_failed: bool;
    error: Csv_Error;
    record_offset: int;
    record_line: int;
    record_line_start: int;
    record_position: int;
    record_scanned: bool;
}
Csv_Readerstructsince 0.36.1Source

A reader over CSV bytes or a chunk source. Create it with csv_reader, advance it with csv_next (or for row: reader) and release it with csv_reader_free. Row is the struct each record is decoded into; the default void reads records as [] string. Once reading stops, reader.error says why (.NONE at the end of the input). The reader's own storage uses the allocator that was current when it was made; a typed row uses the one current at the call.

Csv_Reader :: struct(Row: Type = void) {
    #as using core: Csv_Core;
}