Quote strategies

Fields in CSV files can be enclosed in quotes. Although the CSV specification requires quotes only when a field contains a separator, delimiter, or enclosure character, some applications may always enclose fields in quotes for consistency or simplicity.

From a specification standpoint, these two examples are data identical:

example1.csv

"field 1","field 2","field 3"

example2.csv

field 1,field 2,field 3

However, certain use cases may require enclosing fields to convey a different meaning. For example, this can help distinguish between fields containing an empty string and those with no value at all (null fields).

FastCSV addresses this need by offering various quote strategies. You may also check the corresponding Javadoc for more information.

Writing fields with different quote strategies

In the following example, CSV output is created using different quote strategies.

ExampleCsvWriterWithQuoteStrategy.java

package example;

import de.siegmar.fastcsv.writer.CsvWriter;
import de.siegmar.fastcsv.writer.QuoteStrategies;
import de.siegmar.fastcsv.writer.QuoteStrategy;

/**
 * Example for writing CSV data with different quote strategies.
 */
public class ExampleCsvWriterWithQuoteStrategy {

    public static void main(final String[] args) {
        System.out.println("Quote always");
        CsvWriter.builder()
            .quoteStrategy(QuoteStrategies.ALWAYS)
            .toConsole()
            .writeRecord("value1", "", null, "value,4");

        System.out.println("Quote non-empty");
        CsvWriter.builder()
            .quoteStrategy(QuoteStrategies.NON_EMPTY)
            .toConsole()
            .writeRecord("value1", "", null, "value,4");

        System.out.println("Quote empty");
        CsvWriter.builder()
            .quoteStrategy(QuoteStrategies.EMPTY)
            .toConsole()
            .writeRecord("value1", "", null, "value,4");

        System.out.println("Quote custom");
        CsvWriter.builder()
            .quoteStrategy(customQuote())
            .toConsole()
            .writeRecord("value1", "", null, "value,4");
    }

    // A quote strategy can be used to force quote fields that would otherwise not be quoted.
    private static QuoteStrategy customQuote() {
        return new QuoteStrategy() {
            @Override
            public boolean quoteNull(final int lineNo, final int fieldIdx) {
                // Default implementation returns false
                return false;
            }

            @Override
            public boolean quoteEmpty(final int lineNo, final int fieldIdx) {
                // Default implementation returns false
                return false;
            }

            @Override
            public boolean quoteNonEmpty(final int lineNo, final int fieldIdx, final String value) {
                // Default implementation returns false
                return "value1".equals(value);
            }
        };
    }

}

You also find this source code example in the FastCSV GitHub repository.

Reading quoted fields

To determine if a field is enclosed in quotes when reading a CSV file, additional work and an extra object per field are required. FastCSV does not support this feature out of the box, but it can be implemented using a custom callback handler.

ExampleCsvReaderWithSpecialQuotedFieldHandling.java

package example;

import java.util.ArrayList;
import java.util.List;

import de.siegmar.fastcsv.reader.AbstractBaseCsvCallbackHandler;
import de.siegmar.fastcsv.reader.CsvReader;
import de.siegmar.fastcsv.reader.RecordWrapper;

/**
 * Example for reading CSV data with custom handling of quoted fields.
 */
public class ExampleCsvReaderWithSpecialQuotedFieldHandling {

    private static final String DATA = """
        "quoted foo",unquoted foo
        """;

    public static void main(final String[] args) {
        CsvReader.builder()
            .skipEmptyLines(false)
            .build(new QuotableFieldHandler(), DATA)
            .forEach(System.out::println);
    }

    static class QuotableFieldHandler extends AbstractBaseCsvCallbackHandler<List<QuotableField>> {

        private final List<QuotableField> fields = new ArrayList<>();

        @Override
        protected void handleField(final int fieldIdx,
                                   final char[] buf, final int offset, final int len,
                                   final boolean quoted) {
            final String value = new String(buf, offset, len);
            fields.add(new QuotableField(value, quoted));
        }

        @Override
        protected void handleBegin(final long startingLineNumber) {
            fields.clear();
        }

        @Override
        protected RecordWrapper<List<QuotableField>> buildRecord() {
            return wrapRecord(List.copyOf(fields));
        }

    }

    record QuotableField(String field, boolean quoted) {
    }

}

You also find this source code example in the FastCSV GitHub repository.