Vince's CSV Parser
Loading...
Searching...
No Matches
Vince's CSV Library

This is the detailed documentation for Vince's CSV library. For quick examples, go to this project's GitHub page.

Python users should start with the fastpycsv Python bindings.

For exception-disabled builds and engine-owned resources, see No-exceptions and Godot integration.

Outline

CSV Reading

See also

CSV Tuning

Working with parsed data

See also

Scalar Conversion Reference

DataFrame

An in-memory table built from a csv::CSVReader or a batch of csv::CSVRow values. Frames support positional access, optional keyed lookup, column extraction, editing, and grouping.

ETL Utilities

  • csv::csv_data_types(): Infer SQL-friendly column data types from a CSVReader or any supported CSVReader constructor input
  • csv::chunk_parallel_apply(): Chunked parallel column processing over a CSVReader

See also

High Performance ETL

Deep Dives

Implementation notes and internal architecture documents are collected under Internal / Deep Dives.

CSV Writing

The CSV Writing Guide contains a high-level overview of writing CSVs.

Frequently Asked Questions

How does automatic starting row detection work?

See "How does automatic delimiter detection work?"

How does automatic delimiter detection work?

For each candidate delimiter, the reader groups sampled rows by field count and scores each group as its field count multiplied by its row count. The delimiter with the highest group score wins. Header detection uses the first row when it has at least the winning group's field count; otherwise it uses the first row in that group. Configure csv::CSVFormat explicitly when the format is known.

Is the CSV parser thread-safe?

This library already does a lot of work behind the scenes to use threads to squeeze performance from your CPU. However, ambitious users who are in the mood for experimenting should follow these guidelines:

  • Treat each csv::CSVReader as a single-consumer object. Do not concurrently call row-consumption APIs, iterate, mutate, or destroy the same reader from user threads.
  • A reader's own background worker may still overlap an ordinary single-threaded caller after rows have been queued. csv::CSVReader::speculative_diagnostics() returns a coherent snapshot rather than counters from a partially completed merge.
  • That metadata guarantee is narrow: it does not make other operations on a shared csv::CSVReader generally thread-safe.
  • csv::CSVReader::iterator should only be used from one thread
    • A workaround is to chunk blocks of CSVRow objects together and create separate threads to process each column
  • csv::CSVRow may be safely processed from multiple threads
  • csv::CSVField objects should only be read from one thread at a time