Skip to content

osiegmar/FastCSV

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

FastCSV

FastCSV is an ultra-fast, dependency-free and RFC-compliant CSV library for Java.

build Codacy Badge codecov javadoc Maven Central


The primary use cases of FastCSV are:

  • in big data applications: read and write data on a massive scale
  • in small data applications: a lightweight library without any further dependencies

Benchmark & Compatibility

A selected benchmark from the Java CSV library benchmark suite project:

Benchmark

While maintaining high performance, FastCSV is a strict RFC 4180 CSV writer but also able to read garbled CSV data (to some degree). See JavaCsvComparison for details.

Features

Library specific

  • Ultra fast
  • Small footprint
  • Zero runtime dependencies
  • Null-free
  • Works with GraalVM Native Image
  • OSGi capable

CSV specific

  • Compliant to RFC 4180 – including:
    • Newline and field separator characters in fields
    • Quote escaping
  • Configurable field separator
  • Support for line endings CRLF (Windows), CR (old macOS) and LF (Unix)
  • Unicode support

Reader specific

  • Support reading of some non-compliant (real world) data
  • Preserving line break character(s) within fields
  • Preserving the starting line number (even with skipped and multi line records) – helpful for error messages
  • Auto-detection of line delimiters (can also be mixed)
  • Configurable data validation
  • Support for (optional) header records (get field based on field name)
  • Support for skipping empty records
  • Support for commented lines (skipping & reading) and configurable comment character
  • BOM support (UTF-8, UTF-16 and UTF-32 with little- or big-endian)

Writer specific

  • Support for multiple quote strategies to differentiate between empty and null
  • Support for writing comments with proper quotation if needed

Requirements

  • for 3.x version: Java 11 (Android 13 / API level 33)
  • for 2.x version: Java 8 (Android 8 / API level 26)

💡 Android is not Java and is not officially supported. Although some basic checks are included in the continuous integration pipeline in order to verify that the library should work with Android.

CsvReader examples

Iterative reading of some CSV data from a string

CsvReader.builder().build("foo1,bar1\nfoo2,bar2")
    .forEach(System.out::println);

Iterative reading of a CSV file

try (CsvReader csv = CsvReader.builder().build(path)) {
    csv.forEach(System.out::println);
}

Custom settings

CsvReader.builder()
    .fieldSeparator(';')
    .quoteCharacter('"')
    .commentStrategy(CommentStrategy.SKIP)
    .commentCharacter('#')
    .skipEmptyLines(true)
    .ignoreDifferentFieldCount(false)
    .detectBomHeader(false)
    .fieldModifier(FieldModifier.TRIM);

NamedCsvReader examples

Iterative reading of some CSV data with a header

CsvReader csvReader = CsvReader.builder().build("header 1,header 2\nfield 1,field 2");
NamedCsvReader.from(csvReader)
    .forEach(csvRecord -> System.out.println(csvRecord.getField("header 2")));

Iterative reading of some CSV data with a custom header

List<String> header = List.of("header 1", "header 2");
CsvReader csvReader = CsvReader.builder().build("field 1,field 2");
NamedCsvReader.from(csvReader)
    .forEach(csvRecord -> System.out.println(csvRecord.getField("header 2")));

IndexedCsvReader examples

Indexed reading of a CSV file

try (IndexedCsvReader csv = IndexedCsvReader.builder().build(file)) {
    CsvIndex index = csv.index();

    System.out.println("Items of last page:");
    int lastPage = index.pageCount() - 1;
    List<CsvRecord> csvRecords = csv.readPage(lastPage);
    csvRecords.forEach(System.out::println);
}

CsvWriter examples

Iterative writing of some data to a writer

var sw = new StringWriter();
CsvWriter.builder().build(sw)
    .writeRecord("header1", "header2")
    .writeRecord("value1", "value2");

System.out.println(sw);

Iterative writing of a CSV file

try (CsvWriter csv = CsvWriter.builder().build(path)) {
    csv
        .writeRecord("header1", "header2")
        .writeRecord("value1", "value2");
}

Custom settings

CsvWriter.builder()
    .fieldSeparator(',')
    .quoteCharacter('"')
    .quoteStrategy(QuoteStrategy.ALWAYS)
    .commentCharacter('#')
    .lineDelimiter(LineDelimiter.LF);

More examples

For more examples see example/src/main/java/example/.

Upgrading from an older version

Please see UPGRADING.md for a list of breaking changes in version 3 and how to upgrade.


Sponsoring and partnerships

YourKit

YourKit was used to optimize the performance and footprint of FastCSV. YourKit is the creator of YourKit Java Profiler, YourKit .NET Profiler, and YourKit YouMonitor.