csv 2.0.1

  • README.md
  • Installing
  • Versions
  • --

csv #

A dart csv to list codec / converter.

final csvCodec = new CsvCodec();

csvCodec.encoder.convert([['a', 'b'], [1, 2]]);
// or
final encoder = ListToCsvConverter();
encoder.convert([['a', 'b'], [1, 2]]);

final stream = new Stream.fromIterable([['a', 'b'], [1, 2]]);
final csvRowStream = stream.transform(csvCodec.encoder);
// or
final decoder = CsvToListConverter();

final stream = new Stream.fromIterable(['a,', 'b\r\n12,3.14']);
final listStream = stream.transform(csvCodec.decoder);

var det = new FirstOccurenceSettingsDetector(eols: ['\r\n', '\n']);
var converter = new CsvToListConverter(csvSettingsDetector: det);
// assume someStream is a string stream
someStream.transfrom(converter); // will output another stream of lists.

Build Status

The decoder #

Every csv row is converted to a list of values. Unquoted strings looking like numbers (integers and doubles) are by default converted to ints or doubles.

The encoder #

The input must be a List of Lists. Every inner list is converted to one output csv row. The string representation of values is obtained by calling toString.

This converter follows the rules of rfc4180.

This means that text fields containing any delimiter or an eol are quoted.

The default configuration is:

  • , as field separator
  • " as text delimiter and
  • \r\n as eol.

This parser will accept eol and text-delimiters inside unquoted text and not throw an error.

In addition this converter supports multiple characters for all delimiters and eol. Also the start text delimiter and end text delimiter may be different. This means the following text can be parsed: «abc«d»*|*«xy»»z»*|*123 And (if configured correctly) will return ['abc«d', 'xy»z', 123]

Usage #

Encoder List<List>String

If the default values are fine, simply instantiate ListToCsvConverter and call convert:

final res = const ListToCsvConverter().convert([[',b', 3.1, 42], ['n\n']]);
assert(res == '",b",3.1,42\r\n"n\n"');

There are 2 interesting things to note:

  • Not all rows have to be the same length.
  • The default eol is '\r\n' and '\n' is also quoted. The apparence of only one character is enough for the string to be quoted.

The converter takes the following configurations either in the constructor or the convert function:

  • fieldDelimiter: the separator between fields. By default ',' but another common value is ';'.
  • textDelimiter: the quotation string. By default '"'.
  • textEndDelimiter: the end quotation string. By default equals textDelimiter. This is the string used to end a quoted string.
  • eol: The new line string. By default '\r\n'. Another common value: '\n'

All configuration values may be multiple characters!:

const conv = const ListToCsvConverter(fieldDelimiter: '|*|',
                                      textDelimiter: '<<',
                                      textEndDelimiter: '>>',
                                      eol: '**\n');
final res = conv.convert([['a','>'], ['<<', '>>'], [1, 2]]);
assert(res == 'a|*|<<>>>**\n<<<<>>|*|<<>>>>>>**\n1|*|2');

final res2 = const ListToCsvConverter()
    .convert([['a','>'], ['<<', '>>'], [1, 2]],
             fieldDelimiter: '|*|',
             textDelimiter: '<<',
             textEndDelimiter: '>>',
             eol: '**\n');
assert(res == res2);

Note that:

  • '>' is quoted
  • `'<<' is quoted as well, but because it is "only" a start text delimiter it is not doubled. (See rule 7. below).
  • '>>' is quoted. Only the end-quote string is doubled!

Decoder StringList<List>

If the default values are fine, simply instantiate CsvToListConverter and call convert:

final res = const CsvToListConverter().convert('",b",3.1,42\r\n"n\n"');
assert(res.toString() == [[',b', 3.1, 42], ['n\n']].toString());

Again please note that depending on the input not all rows have the same number of values.

The CsvToListConverter takes the same arguments as the ListToCsvConverter plus

  • parseNumbers: by default true. If you want the output to be Strings only set this to false.

  • allowInvalid: by default true. The converter will by default never throw an exception. Even if fieldDelimiter, textDelimiter,... don't make sense or the csv-String is invalid. This may for instance happen if the csv-String ends with a quoted String without the end-quote (textEndDelimiter) string.

  • csvSettingsDetector: must be an object which extends from CsvSettingsDetector. There is a simple implementation which simply uses the first occurence of a list of possible values as value.

    var d = new FirstOccurenceSettingsDetector(eols: ['\r\n', '\n'], textDelimiters: ['""', "'"]);

new CsvToListConverter(csvSettingsDetector: d);

In this case eol will either be '\r\n' or '\n' depending on which of those 2 comes first in the csv string. Note that the FirstOccurenceSettingsDetector doesn't parse the csv string! For instance if eol should be '\r\n' but there is a field with '\n' in the first row, '\n' is used instead.

To check your configuration values there is CsvToListConverter.verifySettings and verifyCurrentSettings. Both return a list of errors or if the optional throwError is true, throw in case there is an error.

CSV rules -- copied from RFC4180 Chapter 2 #

Ad rule 3: removed as it is not relevant for this converter.

  1. Each record is located on a separate line, delimited by a line break (CRLF). For example: aaa,bbb,ccc CRLF zzz,yyy,xxx CRLF

  2. The last record in the file may or may not have an ending line break. For example: aaa,bbb,ccc CRLF zzz,yyy,xxx

  3. ... (Header-lines)

  4. Within the header and each record, there may be one or more fields, separated by commas. Each line should contain the same number of fields throughout the file. Spaces are considered part of a field and should not be ignored. The last field in the record must not be followed by a comma. For example:


  5. Each field may or may not be enclosed in double quotes (however some programs, such as Microsoft Excel, do not use double quotes at all). If fields are not enclosed with double quotes, then double quotes may not appear inside the fields. For example:

    "aaa","bbb","ccc" CRLF zzz,yyy,xxx

  6. Fields containing line breaks (CRLF), double quotes, and commas should be enclosed in double-quotes. For example:

    "aaa","b CRLF bb","ccc" CRLF zzz,yyy,xxx

  7. If double-quotes are used to enclose fields, then a double-quote appearing inside a field must be escaped by preceding it with another double quote. For example:


Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  csv: ^2.0.1

2. Install it

You can install packages from the command line:

with pub:

$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:csv/csv.dart';
Version Uploaded Documentation Archive
4.0.3 Apr 5, 2019 Go to the documentation of csv 4.0.3 Download csv 4.0.3 archive
4.0.2 Mar 9, 2019 Go to the documentation of csv 4.0.2 Download csv 4.0.2 archive
4.0.1 Nov 17, 2018 Go to the documentation of csv 4.0.1 Download csv 4.0.1 archive
4.0.0 Jul 3, 2018 Go to the documentation of csv 4.0.0 Download csv 4.0.0 archive
3.3.0 Jul 3, 2018 Go to the documentation of csv 3.3.0 Download csv 3.3.0 archive
3.2.0 Jun 26, 2018 Go to the documentation of csv 3.2.0 Download csv 3.2.0 archive
3.1.2 Feb 15, 2017 Go to the documentation of csv 3.1.2 Download csv 3.1.2 archive
3.1.1 Jun 15, 2016 Go to the documentation of csv 3.1.1 Download csv 3.1.1 archive
3.0.1 Feb 1, 2016 Go to the documentation of csv 3.0.1 Download csv 3.0.1 archive
2.0.1 Oct 5, 2014 Go to the documentation of csv 2.0.1 Download csv 2.0.1 archive

All 11 versions...

Awaiting analysis to complete.