README
¶
go-zerocsv
go-zerocsv is a zero-allocation CSV reader and writer for Go. It reads and writes CSV records without heap-allocating per record, so throughput stays high and memory use stays flat no matter how large the file is.
Features
- Zero allocations on the hot path: each
Writeand eachNextparses without heap allocation; the buffer and field slices are allocated once and reused. - Zero dependencies: relies exclusively on the Go standard library.
- Fuzz-tested parity: reader output is conformance-fuzzed against
encoding/csvin both strict and lazy-quote modes. - Flat memory: the reader holds one reusable buffer regardless of input size, so a 5M-row file costs roughly as much memory as a 100-row one.
Installation
Requires Go 1.18 or higher (for any and native fuzzing).
go get github.com/fikrimohammad/go-zerocsv
Quick Start
Writing
package main
import (
"bytes"
"fmt"
zerocsv "github.com/fikrimohammad/go-zerocsv"
)
func main() {
var buf bytes.Buffer
w := zerocsv.New(&buf)
w.Write(
zerocsv.ColumnString("name"),
zerocsv.ColumnInt(30),
zerocsv.ColumnBool(true),
)
w.Flush()
fmt.Print(buf.String())
// name,30,true
}
Reading
package main
import (
"fmt"
"io"
"log"
"strings"
zerocsv "github.com/fikrimohammad/go-zerocsv"
)
func main() {
input := "name,age\nAlice,30\nBob,40\n"
r := zerocsv.NewReader(strings.NewReader(input))
for {
rec, err := r.Next()
if err == io.EOF {
break
}
if err != nil {
log.Fatal(err)
}
for i := 0; i < rec.Len(); i++ {
fmt.Printf("%d:%s ", i, rec.ValueAt(i))
}
fmt.Println()
}
}
Advanced Usage
Custom options
Options are shared by the writer and reader; each applies only to the side it concerns.
// Tab-separated values.
w := zerocsv.New(&buf, zerocsv.WithDelimiter('\t'))
// CRLF line endings instead of LF.
w := zerocsv.New(&buf, zerocsv.WithCRLF())
// Tolerate malformed quoting instead of returning a parse error.
r := zerocsv.NewReader(f, zerocsv.WithLazyQuotes())
Typed columns
w.Write(
zerocsv.ColumnInt64(42),
zerocsv.ColumnFloat64(3.14),
zerocsv.ColumnTime(time.Now(), time.RFC3339),
zerocsv.ColumnBytes([]byte("raw")),
)
Zero-allocation writing loop
Reuse one []Column slice across writes so nothing is allocated per record.
row := make([]zerocsv.Column, 3)
for _, v := range values {
row[0] = zerocsv.ColumnString(v.Name)
row[1] = zerocsv.ColumnInt(v.Age)
row[2] = zerocsv.ColumnBool(v.Active)
_ = w.Write(row...)
}
Zero-copy reading
ValueAt returns a zero-copy view into the reader's reused buffer. The value
is valid only until the next Next call. Convert it to a string to own the
data, since string([]byte) copies:
for {
rec, err := r.Next()
if err == io.EOF {
break
}
if err != nil {
log.Fatal(err)
}
name := string(rec.ValueAt(0)) // owned copy, safe to retain
_ = name
}
Documentation
Full API documentation and runnable examples are available on pkg.go.dev.
Concurrency
Writer and Reader are stateful and not safe for concurrent use. Use a
separate instance per goroutine.
Contributing
- Fork the repository.
- Create your feature branch (
git checkout -b feature/amazing-feature). - Commit your changes (
git commit -m 'Add some amazing feature'). - Push to the branch (
git push origin feature/amazing-feature). - Open a Pull Request.
Local Quality Checks
Make sure to run the linters and tests locally before submitting your code:
# Run golangci-lint locally
golangci-lint run ./...
# Run tests with the race detector enabled
go test -race -count=1 ./...
# Smoke-test the fuzzers (anchor the pattern so it matches one target)
go test -run='^$' -fuzz='^FuzzReaderConformance$' -fuzztime=30s ./...
License
Distributed under the MIT License. See LICENSE for more information.
Documentation
¶
Index ¶
- Variables
- type Column
- func ColumnAny(v any) Column
- func ColumnBool(v bool) Column
- func ColumnBytes(b []byte) Column
- func ColumnFloat32(v float32) Column
- func ColumnFloat64(v float64) Column
- func ColumnInt(v int) Column
- func ColumnInt8(v int8) Column
- func ColumnInt16(v int16) Column
- func ColumnInt32(v int32) Column
- func ColumnInt64(v int64) Column
- func ColumnString(s string) Column
- func ColumnTime(t time.Time, layout string) Column
- func ColumnUint(v uint) Column
- func ColumnUint8(v uint8) Column
- func ColumnUint16(v uint16) Column
- func ColumnUint32(v uint32) Column
- func ColumnUint64(v uint64) Column
- func ColumnUintptr(v uintptr) Column
- type ColumnKind
- type Option
- type Reader
- type Record
- type Writer
Constants ¶
This section is empty.
Variables ¶
var ErrBareQuote = errors.New("bare \" in non-quoted field")
ErrBareQuote is returned when a bare '"' appears in a non-quoted field.
var ErrQuote = errors.New("extraneous or missing \" in quoted-field")
ErrQuote is returned for an extraneous or missing '"' in a quoted field.
Functions ¶
This section is empty.
Types ¶
type Column ¶
type Column struct {
// contains filtered or unexported fields
}
Column is a tagged, value-typed CSV field. Pass it to Write by value; it holds no pointers that escape, so building and writing columns performs no heap allocation.
func ColumnAny ¶
ColumnAny returns a Column containing v, rendered with fmt.Sprint when the record is written. Unlike the typed constructors, this may allocate.
func ColumnBool ¶
ColumnBool returns a Column containing v, written as "true" or "false".
func ColumnBytes ¶
ColumnBytes returns a Column containing b. The slice is written as-is, with no copy.
func ColumnFloat32 ¶
ColumnFloat32 returns a Column containing v.
func ColumnFloat64 ¶
ColumnFloat64 returns a Column containing v.
func ColumnTime ¶
ColumnTime returns a Column containing t, formatted with layout when the record is written.
func ColumnUintptr ¶
ColumnUintptr returns a Column containing v.
type Option ¶
type Option func(*options)
Option configures a Writer or Reader at construction time.
func WithCRLF ¶
func WithCRLF() Option
WithCRLF makes the Writer end each record with "\r\n" instead of "\n".
func WithDelimiter ¶
WithDelimiter sets the field delimiter, for example ',' for CSV, '\t' for TSV, or ';' for semicolon-separated values. The NUL byte, '"', '\r' and '\n' are rejected: an invalid delimiter marks the Writer as failed, and Write, WriteAll, Flush and Error report the error.
func WithLazyQuotes ¶
func WithLazyQuotes() Option
WithLazyQuotes makes the Reader tolerate malformed quoting: a bare '"' in an unquoted field, or a non-doubled '"' in a quoted field, is treated as a literal character instead of returning a parse error.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader reads CSV records with zero allocations per record.
The input buffer and the field slice are allocated once in NewReader and reused for the lifetime of the Reader. The fields of a Record returned by Next are zero-copy views into that buffer, so they are valid only until the next call to Next.
func (*Reader) Next ¶
Next parses and returns the next record, or io.EOF when no records remain. It returns ErrBareQuote or ErrQuote for malformed quoting, unless WithLazyQuotes is in effect, and propagates any error from the underlying reader.
The returned Record is reused by the Reader and overwritten by each call to Next. Its fields are zero-copy views into the Reader's internal buffer and are valid only until the next call to Next, like encoding/csv's ReuseRecord mode. Copy a field with slices.Clone, or convert it to a string, if it must outlive the read loop.
type Record ¶
type Record struct {
// contains filtered or unexported fields
}
Record is a parsed CSV record. The Reader reuses a single Record and overwrites it on every call to Next, so a Record is valid only until the Reader is advanced again. Its fields are zero-copy views into the Reader's internal buffer; copy one with slices.Clone, or convert it to a string (which copies), if it must outlive the read loop.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer writes CSV records with zero allocations per write.
The bufio.Writer and the numeric scratch buffer are allocated once in New and reused for the lifetime of the Writer. Write/WriteAll perform no heap allocations on the hot path as long as the caller reuses a []Column slice (e.g. Write(row...)) rather than passing freshly constructed variadic args.
func New ¶
New returns a Writer that writes CSV records to w, applying opts. If w is already a *bufio.Writer with a large enough buffer, it is reused directly.
func (*Writer) Error ¶
Error returns the first error encountered during Write, WriteAll or Flush, or nil if none has occurred.
func (*Writer) Flush ¶
Flush writes any buffered data to the underlying writer and returns the first error encountered during Write, WriteAll or Flush, if any.
Source Files
Directories