std.csv

Implements functionality to read Comma Separated Values and its variants from an input range of dchar.

Comma Separated Values provide a simple means to transfer and store tabular data. It has been common for programs to use their own variant of the CSV format. This parser will loosely follow the RFC-4180. CSV input should adhere to the following criteria (differences from RFC-4180 in parentheses):

  • A record is separated by a new line (CRLF,LF,CR)
  • A final record may end with a new line
  • A header may be provided as the first record in input
  • A record has fields separated by a comma (customizable)
  • A field containing new lines, commas, or double quotes should be enclosed in double quotes (customizable)
  • Double quotes in a field are escaped with a double quote
  • Each record should contain the same number of fields

Members

Classes

CSVException
class CSVException

Exception containing the row and column for when an exception was thrown.

HeaderMismatchException
class HeaderMismatchException

Exception thrown under different conditions based on the type of Contents.

IncompleteCellException
class IncompleteCellException

Exception thrown when a Token is identified to not be completed: a quote is found in an unquoted field, data continues after a closing quote, or the quoted field was not closed before data was empty.

Enums

Malformed
enum Malformed

* Determines the behavior for when an error is detected. * * Disabling exception will follow these rules: *

    *
  • A quote can appear in a field if the field was not quoted.
  • *

  • If in a quoted field any quote by itself, not at the end of a * field, will end processing for that field.
  • *

  • The field is ended when there is no input, even if the quote was * not closed.
  • *

  • If the given header does not match the order in the input, the * content will return as it is found in the input.
  • *

  • If the given header contains columns not found in the input they * will be ignored.
  • *

Functions

csvNextToken
void csvNextToken(Range input, Output ans, Separator sep, Separator quote, bool startQuoted)

Lower level control over parsing CSV

csvReader
auto csvReader(Range input, Header header, Separator delimiter, Separator quote, bool allowInconsistentDelimiterCount)

Returns an input range for iterating over records found in input.

csvReader
auto csvReader(Range input, Separator delimiter, Separator quote, bool allowInconsistentDelimiterCount)

Returns an input range for iterating over records found in input.

Examples

import std.algorithm;
import std.array;
import std.csv;
import std.stdio;
import std.typecons;

void main()
{
    auto text = "Joe,Carpenter,300000\nFred,Blacksmith,400000\r\n";

    foreach (record; csvReader!(Tuple!(string, string, int))(text))
    {
        writefln("%s works as a %s and earns $%d per year",
                 record[0], record[1], record[2]);
    }

    // To read the same string from the file "filename.csv":

    auto file = File("filename.csv", "r");
    foreach (record;
        file.byLine.joiner("\n").csvReader!(Tuple!(string, string, int)))
    {
        writefln("%s works as a %s and earns $%d per year",
                 record[0], record[1], record[2]);
    }
 }
}

When an input contains a header the Contents can be specified as an associative array. Passing null to signify that a header is present.

auto text = "Name,Occupation,Salary\r" ~
    "Joe,Carpenter,300000\nFred,Blacksmith,400000\r\n";

foreach (record; csvReader!(string[string])
        (text, null))
{
    writefln("%s works as a %s and earns $%s per year.",
             record["Name"], record["Occupation"],
             record["Salary"]);
}

// To read the same string from the file "filename.csv":

auto file = File("filename.csv", "r");

foreach (record; csvReader!(string[string])
        (file.byLine.joiner("\n"), null))
{
    writefln("%s works as a %s and earns $%s per year.",
             record["Name"], record["Occupation"],
             record["Salary"]);
}

This module allows content to be iterated by record stored in a struct, class, associative array, or as a range of fields. Upon detection of an error an CSVException is thrown (can be disabled). csvNextToken has been made public to allow for attempted recovery.

Disabling exceptions will lift many restrictions specified above. A quote can appear in a field if the field was not quoted. If in a quoted field any quote by itself, not at the end of a field, will end processing for that field. The field is ended when there is no input, even if the quote was not closed.

See Also

Meta

Authors

Jesse Phillips