# gizlang:csv

CSV retains bytes and reuses one record's range table: no field copies in next/field/integer. text alone decodes; number reads the range in place (Text.decimalPrefix). Field ranges refer to the caller's input.

```gizlang
import * as Csv from "gizlang:csv";
```

## Types

### `CsvError`

```gizlang
type CsvError = { offset: i64; message: string; }
```

A CSV failure: the byte offset and what is wrong.

- `offset`: `i64`
- `message`: `string`

### `Field`

```gizlang
type Field = { start: i64; end: i64; escaped: bool; }
```

A field of a CSV record: where it starts and ends in the text, and whether it is quoted with escapes.

- `start`: `i64`
- `end`: `i64`
- `escaped`: `bool`

### `CsvReader`

```gizlang
type CsvReader
```

A reader of CSV text, record by record.

Opaque: create and use it through this module's functions.

### `CsvLayout`

```gizlang
type CsvLayout = { maxColumns: i64; maxFieldBytes: i64; maxRecordBytes: i64; firstRecordBytes: i64; position: i64; records: i64; firstColumns: i64; uniformRecords: i64; }
```

Scalar admission measurements for the complete prefix. Field bytes are the
retained raw content span, excluding surrounding quotes but including doubled
quotes. Record bytes include delimiters, quoting and any LF/CRLF terminator.
uniformRecords counts the consecutive prefix with firstColumns fields; it
stops at the first width mismatch, independently of later record widths.

- `maxColumns`: `i64`
- `maxFieldBytes`: `i64`
- `maxRecordBytes`: `i64`
- `firstRecordBytes`: `i64`
- `position`: `i64`
- `records`: `i64`
- `firstColumns`: `i64`
- `uniformRecords`: `i64`

### `CsvWriter`

```gizlang
type CsvWriter
```

Writer owns its output. Fields append to that buffer; escaping copies runs
and doubles quote bytes only when required. end emits RFC 4180 CRLF.

Opaque: create and use it through this module's functions.

## Functions

### `reader`

```gizlang
function reader(data: bytes): CsvReader
```

A reader of the CSV text `data`.

### `layout`

```gizlang
function layout(data: bytes, delimiter: u64, quote: u64, final: bool, maxRecords: i64): CsvLayout throws CsvError
```

Use the reader's exact grammar without retaining fields or decoding text.
A nonfinal incomplete tail contributes no measurements; malformed input
reports the same first error as nextAvailable, including in that tail.
maxRecords=0 scans the full input. A positive limit stops after that many
committed records without examining the remainder; a negative limit is invalid.

Effects: fail.

### `writer`

```gizlang
function writer(): CsvWriter
```

A writer of CSV with comma as the delimiter and `"` as the quote.

## Methods

### `CsvReader.format`

```gizlang
function CsvReader.format(self: mut CsvReader, delimiter: u64, quote: u64): bool
```

Configure before reading. Invalid configuration stops the reader as data
errors do; arbitrary distinct bytes except CR/LF are supported.

Effects: fail.

### `CsvReader.error`

```gizlang
function CsvReader.error(self: CsvReader): Option<CsvError>
```

The error that stopped the reader, if there is one.

### `CsvReader.next`

```gizlang
function CsvReader.next(self: mut CsvReader): bool
```

Empty input has no records. An empty line is one empty field; a final
delimiter adds an empty field, a final newline does not add a record.

Effects: fail.

### `CsvReader.nextAvailable`

```gizlang
function CsvReader.nextAvailable(self: mut CsvReader, final: bool): bool
```

A nonfinal byte window never commits its unfinished last record. Field ranges
and grammar are shared with final next(); false without error asks for more bytes.

Effects: fail.

### `CsvReader.position`

```gizlang
function CsvReader.position(self: CsvReader): i64
```

Bytes consumed through the last complete record, for bounded input-window retention.

### `CsvReader.count`

```gizlang
function CsvReader.count(self: CsvReader): i64
```

The number of fields in the current record.

### `CsvReader.field`

```gizlang
function CsvReader.field(self: CsvReader, index: i64): Option<Field>
```

The field `index` of the current record, if it exists.

Effects: fail.

### `CsvReader.text`

```gizlang
function CsvReader.text(self: CsvReader, index: i64): string throws CsvError
```

Only this operation copies/unescapes a field. Binary fields remain usable
as ranges; invalid UTF-8 or an invalid index is a Result, never a fault.

Effects: fail.

### `CsvReader.number`

```gizlang
function CsvReader.number(self: CsvReader, index: i64): Option<f64>
```

Whole-field decimal syntax, as Text.parseF64, validated in place. Empty,
escaped, non-numeric and missing fields return none, without changing error.

Effects: fail.

### `CsvReader.integer`

```gizlang
function CsvReader.integer(self: CsvReader, index: i64): Option<i64>
```

Exact i64, accumulating negatively so MIN is representable; no string.

Effects: fail.

### `CsvWriter.format`

```gizlang
function CsvWriter.format(self: mut CsvWriter, delimiter: u64, quote: u64): bool
```

Set the delimiter and the quote byte; false if they are not valid.

Effects: fail.

### `CsvWriter.error`

```gizlang
function CsvWriter.error(self: CsvWriter): Option<CsvError>
```

The error that stopped the writer, if there is one.

### `CsvWriter.field`

```gizlang
function CsvWriter.field(self: mut CsvWriter, value: bytes): void
```

Write one field of the current record, quoted when it needs it.

Effects: fail.

### `CsvWriter.end`

```gizlang
function CsvWriter.end(self: mut CsvWriter): void
```

End the current record.

Effects: fail.

### `CsvWriter.data`

```gizlang
function CsvWriter.data(self: CsvWriter): bytes
```

The CSV text written so far.

gizlang:csv

CSV retains bytes and reuses one record's range table: no field copies in next/field/integer. text alone decodes; number reads the range in place (Text.decimalPrefix). Field ranges refer to the caller's input.

gizlang

import * as Csv from "gizlang:csv";

Types

`CsvError`

gizlang

type CsvError = { offset: i64; message: string; }

A CSV failure: the byte offset and what is wrong.

offset: i64
message: string

`Field`

gizlang

type Field = { start: i64; end: i64; escaped: bool; }

A field of a CSV record: where it starts and ends in the text, and whether it is quoted with escapes.

start: i64
end: i64
escaped: bool

`CsvReader`

gizlang

type CsvReader

A reader of CSV text, record by record.

Opaque: create and use it through this module's functions.

`CsvLayout`

gizlang

type CsvLayout = { maxColumns: i64; maxFieldBytes: i64; maxRecordBytes: i64; firstRecordBytes: i64; position: i64; records: i64; firstColumns: i64; uniformRecords: i64; }

Scalar admission measurements for the complete prefix. Field bytes are the retained raw content span, excluding surrounding quotes but including doubled quotes. Record bytes include delimiters, quoting and any LF/CRLF terminator. uniformRecords counts the consecutive prefix with firstColumns fields; it stops at the first width mismatch, independently of later record widths.

maxColumns: i64
maxFieldBytes: i64
maxRecordBytes: i64
firstRecordBytes: i64
position: i64
records: i64
firstColumns: i64
uniformRecords: i64

`CsvWriter`

gizlang

type CsvWriter

Writer owns its output. Fields append to that buffer; escaping copies runs and doubles quote bytes only when required. end emits RFC 4180 CRLF.

Opaque: create and use it through this module's functions.

Functions

`reader`

gizlang

function reader(data: bytes): CsvReader

A reader of the CSV text data.

`layout`

gizlang

function layout(data: bytes, delimiter: u64, quote: u64, final: bool, maxRecords: i64): CsvLayout throws CsvError

Use the reader's exact grammar without retaining fields or decoding text. A nonfinal incomplete tail contributes no measurements; malformed input reports the same first error as nextAvailable, including in that tail. maxRecords=0 scans the full input. A positive limit stops after that many committed records without examining the remainder; a negative limit is invalid.

Effects: fail.

`writer`

gizlang

function writer(): CsvWriter

A writer of CSV with comma as the delimiter and " as the quote.

Methods

`CsvReader.format`

gizlang

function CsvReader.format(self: mut CsvReader, delimiter: u64, quote: u64): bool

Configure before reading. Invalid configuration stops the reader as data errors do; arbitrary distinct bytes except CR/LF are supported.

Effects: fail.

`CsvReader.error`

gizlang

function CsvReader.error(self: CsvReader): Option<CsvError>

The error that stopped the reader, if there is one.

`CsvReader.next`

gizlang

function CsvReader.next(self: mut CsvReader): bool

Empty input has no records. An empty line is one empty field; a final delimiter adds an empty field, a final newline does not add a record.

Effects: fail.

`CsvReader.nextAvailable`

gizlang

function CsvReader.nextAvailable(self: mut CsvReader, final: bool): bool

A nonfinal byte window never commits its unfinished last record. Field ranges and grammar are shared with final next(); false without error asks for more bytes.

Effects: fail.

`CsvReader.position`

gizlang

function CsvReader.position(self: CsvReader): i64

Bytes consumed through the last complete record, for bounded input-window retention.

`CsvReader.count`

gizlang

function CsvReader.count(self: CsvReader): i64

The number of fields in the current record.

`CsvReader.field`

gizlang

function CsvReader.field(self: CsvReader, index: i64): Option<Field>

The field index of the current record, if it exists.

Effects: fail.

`CsvReader.text`

gizlang

function CsvReader.text(self: CsvReader, index: i64): string throws CsvError

Only this operation copies/unescapes a field. Binary fields remain usable as ranges; invalid UTF-8 or an invalid index is a Result, never a fault.

Effects: fail.

`CsvReader.number`

gizlang

function CsvReader.number(self: CsvReader, index: i64): Option<f64>

Whole-field decimal syntax, as Text.parseF64, validated in place. Empty, escaped, non-numeric and missing fields return none, without changing error.

Effects: fail.

`CsvReader.integer`

gizlang

function CsvReader.integer(self: CsvReader, index: i64): Option<i64>

Exact i64, accumulating negatively so MIN is representable; no string.

Effects: fail.

`CsvWriter.format`

gizlang

function CsvWriter.format(self: mut CsvWriter, delimiter: u64, quote: u64): bool

Set the delimiter and the quote byte; false if they are not valid.

Effects: fail.

`CsvWriter.error`

gizlang

function CsvWriter.error(self: CsvWriter): Option<CsvError>

The error that stopped the writer, if there is one.

`CsvWriter.field`

gizlang

function CsvWriter.field(self: mut CsvWriter, value: bytes): void

Write one field of the current record, quoted when it needs it.

Effects: fail.

`CsvWriter.end`

gizlang

function CsvWriter.end(self: mut CsvWriter): void

End the current record.

Effects: fail.

`CsvWriter.data`

gizlang

function CsvWriter.data(self: CsvWriter): bytes

The CSV text written so far.