serial_csv

pub package ci License: MIT

High performance CSV encoder and decoder with retained types and nullability.

Introduction

This package is intended to quickly encode and decode csv while keeping all type information.

Its strict nature enhances performance during encoding and decoding.

During this process, the following data types are preserved: String, int, double, bool, null.

Benchmark

The benchmark was run with 2 million rows (1000 rows x 2000 iterations) on an i7-10750H.

For comparison, the packages csv (v5.0.2), fast_csv (v0.1.44), and csvwriter (v1.3.0) were used.

benchmark

You can run the benchmark yourself with this code example.

CSV structure

This library uses a more strict CSV format to achieve high performance.

  • string cells are always double-quoted
  • numeric and boolean cells are not double-quoted
  • null cells are encoded as empty strings
  • double-quotes within cells are escaped with another double-quote
  • cells are separated by commas
  • every row must be terminated with \n (LF)
  • no comments (#) are allowed

Usage

While the encoded CSV is still valid CSV, do not modify it with other tools as you might break the strict format.

So as long as you only use this library, you can be sure that the data types and their nullability are retained.

"a","b","c"
1,2.3,"3"
4,,true

String encoded = SerialCsv.encode([
  ['a', 'b', 'c'],
  [1, 2.3, '3'],
  ['4', null, true],
]);

List<List<dynamic>> decoded = SerialCsv.decode(encoded);

String s = decoded[0][0]; // 'a'
int i = decoded[1][0]; // 1
double d = decoded[1][1]; // 2.3
bool b = decoded[2][2]; // true
Object? n = decoded[2][1]; // null

API

Encode

Encode a list of rows into a csv string.

Example:

const rows = [
  ['a', 'b', 'c'],
  [1, 2, 3.2],
  ['4', null, true],
];
String encoded = SerialCsv.encode(rows);

Decode

Decode a csv string into a list of rows.

Example:

const csv = '"a","b","c"\n1,2.3,"3"\n4,,true\n';
List<List<dynamic>> decoded = SerialCsv.decode(csv);

Specialization

There a specialized methods with optimized performance:

Strings only

Encode and decode a list of rows with only string cells. No null is allowed.

const rows = [
  ['a', 'b', 'c'],
  ['1', '2', '3'],
  ['4', '5', 'true'],
];
String encoded = SerialCsv.encodeStringList(rows);
List<List<String>> decoded = SerialCsv.decodeStringList(encoded);

Key-Value

Encode and decode a non-nested map. Keys must be strings. Values can be any supported type.

const map = {
  'a': '1',
  'b': 2,
  'c': true,
  'd': null,
};

String encoded = SerialCsv.encodeMap(map);
Map<String, dynamic> decoded = SerialCsv.decodeMap(encoded);

Libraries

serial_csv