FastCSV Documentation

FastCSV supports reading and writing CSV files in any encoding supported by Java.

Limitation: FastCSV does not support mixed encodings within a single CSV file; the encoding must be consistent throughout the file.

Since CSV does not natively distinguish between empty fields and null values, FastCSV provides the following mechanisms:

On Writing

Depending on your QuoteStrategy, null values are written as:

• Empty fields (default).
• Quoted empty fields (using QuoteStrategies.EMPTY). This is useful for PostgreSQL compatibility.
• To write a specific string for a null value, pass that string directly to CsvWriter.writeRecord().

On Reading

To distinguish between an empty field and a null value, you can implement a custom CsvRecord that utilizes the quoted parameter provided to CsvCallbackHandler.addField() to check if the field was enclosed in quotes.

1,,fooCRLF
2,"",barCRLF

When reading CSV files that contain comments, you can control how FastCSV treats those lines using the CommentStrategy enum. FastCSV provides three main behaviors:

1. Treat as data (Default): Comments are treated as part of the data to ensure maximum compatibility with the RFC 4180 standard and prevent data loss.
2. Skip comments: The comment lines are ignored during the reading process.
3. Read as comments: The lines are explicitly interpreted as comments.

To use a specific strategy, configure the CsvReaderBuilder.

FastCSV allows you to configure the field separator (e.g., semicolon or tab) and the encapsulation character (e.g., single quotes) to support various real-world CSV formats.

However, the following are not supported:

• Multiple characters: Field separators and encapsulation characters must be a single character.
• Mixed separators/encapsulation: You cannot use different separators or different encapsulation characters within the same file. The configured character is used for the entire file.

FastCSV supports any encoding, defaulting to UTF-8.

Note for IndexedCsvReader: Because it builds its index at the byte level, it is restricted to UTF-8 and single-byte encodings.

FastCSV does not provide a built-in way to check if a field was enclosed in quotes during the reading process. To distinguish between quoted and unquoted fields (which can be useful for differentiating between empty strings and null values), you must implement a custom callback handler using QuotableFieldHandler and QuotableField.

// Implementation pattern for detecting quoted fields
// Requires implementing a custom handler to intercept field metadata
CsvReader reader = CsvReader.builder()
    .fieldHandler(new MyQuotableFieldHandler()) 
    .build(inputStream);

FastCSV is compliant with RFC 4180, which includes support for:

• Newline and field separator characters within fields.
• Quote escaping.
• Configurable field separators.
• Support for CRLF (Windows), LF (Unix), and CR (old macOS) line endings.
• Full Unicode character support.

In FastCSV 4.x, CsvWriter (for both OutputStream and Writer) no longer flushes the internal buffer after every record. It only flushes when the buffer is full, or when flush() or close() is called.

Best Practices:

• Always call close() on the CsvWriter at the end of the process to ensure all data is written.
• Call flush() manually if you need to write to the underlying Writer or OutputStream directly before closing.
• You no longer need to wrap your Writer in a BufferedWriter for performance unless you have explicitly disabled FastCSV's internal buffer using CsvWriterBuilder.bufferSize(0).

The CsvReader is the central entry point for reading CSV data. It uses a builder pattern (CsvReaderBuilder) to configure format specifications (like separators and quote characters) and parsing behavior.

Internally, the CsvReader orchestrates a CsvParser to handle low-level data parsing and a CsvCallbackHandler to materialize fields into records. The CsvReader implements the Iterable interface, allowing you to iterate over parsed records (such as CsvRecord objects) using standard loops or forEach.

try (CsvReader<CsvRecord> csv = CsvReader.builder().ofCsvRecord(file)) {
    csv.forEach(System.out::println);
}