Using records

The Record API has been introduced in univocity-parsers 2.0.0 to provide a convenient and easy to use mechanism for reading input rows, and getting data in a type you expect to use. It’s very simple.

Basic usage

settings.getFormat().setDelimiter(';');
settings.getFormat().setQuoteEscape('\\');

settings.setHeaderExtractionEnabled(true);

CsvParser parser = new CsvParser(settings);

// parses all records in one go
List<Record> allRecords = parser.parseAllRecords(getReader("/examples/european.csv"));

double sumOfPrices = 0.0;
for (Record record : allRecords) {
    //Let's use the convenience methods in the record class to convert the parsed data into a Double.
    //Numbers are stored in the file using the european format.
    //Here we read the "price" column, using the "0,00" format mask, and decimal separator set to comma.
    Double price = record.getDouble("price", "0,00", "decimalSeparator=,");

    if (price != null) {
        sumOfPrices += price;
    }
}

print("Average car price: $" + (sumOfPrices / allRecords.size()));

Here’s the result:

Average car price: $4519.8

Record metadata

You can also access the RecordMetaData to assign conversions and default values to one or more fields:

parser.getRecordMetadata().setTypeOfColumns(Long.class, "year", "price");
parser.getRecordMetadata().setDefaultValueOfColumns("0", "Year");
parser.getRecordMetadata().convertFields(Conversions.replace("\\.00", "")).set("Price");

for (Record record : allRecords) {
    Long year = record.getLong("year");
    String model = record.getString("MODEL");
    Long price = record.getLong("Price");
    println(year + " " + model + ": $" + price);
}

Here’s the result:

1997 E350: $3000
1999 Venture "Extended Edition": $4900
1996 Grand Cherokee: $4799
1999 Venture "Extended Edition, Very Large": $5000
0 Venture "Extended Edition": $4900

From Records to Maps

You can also convert a Record to a Map, or fill an existing Map:

// this time, lest's parse on demand.
parser.beginParsing(getReader("/examples/example.csv"));

//null year should become 0000
parser.getRecordMetadata().setDefaultValueOfColumns("0000", "Year");

//decimal separator in prices will be replaced by comma
parser.getRecordMetadata().convertFields(Conversions.replace("\\.00", ",00")).set("Price");

//make will be uppercase
parser.getRecordMetadata().convertFields(Conversions.toUpperCase()).set("make");

//let's fill a map with values.
LinkedHashMap<String, Object> values = new LinkedHashMap<String, Object>();

//create instances of Record on demand
Record record;
while ((record = parser.parseNextRecord()) != null) {
    //we can get the original values of selected columns (by name or index) in a map.
    //Map<String, String> originalValues = record.toFieldMap();

    //to get the converted values as specified in the record metadata use the method ending with "ObjectMap"
    //Map<String, Object> convertedValues = record.toFieldObjectMap();

    //all map methods allow you to choose which columns to get data from. Here we select just the (originally parsed) year:
    Map<String, String> originalYearValues = record.toFieldMap("YEAR"); //the character case of the selection is kept regardless of what the headers contain.
    println(originalYearValues); //original values, no conversions applied.

    //instead of creating new maps every time, we can also reuse maps and invoke the "fill" methods
    record.fillFieldObjectMap(values);
    println(values);

}

Output:

{YEAR=1997}
{Year=1997, Make=FORD, Model=E350, Description=ac, abs, moon, Price=3000,00}
{YEAR=1999}
{Year=1999, Make=CHEVY, Model=Venture "Extended Edition", Description=null, Price=4900,00}
{YEAR=1996}
{Year=1996, Make=JEEP, Model=Grand Cherokee, Description=MUST SELL!
air, moon roof, loaded, Price=4799,00}
{YEAR=1999}
{Year=1999, Make=CHEVY, Model=Venture "Extended Edition, Very Large", Description=null, Price=5000,00}
{YEAR=null}
{Year=0000, Make=null, Model=Venture "Extended Edition", Description=null, Price=4900,00}

Further Reading

Feel free to proceed to the following sections (in any order).

• Introduction to univocity-parsers
• Reading data into java beans
• Writing
• Routines
• Other Row Processors
• Working with CSV
• Working with TSV
• Working with Fixed-Width

Bugs, contributions & support

If you find a bug, please report it on github or send us an email on parsers@univocity.com.

We try out best to eliminate all bugs as soon as possible and you’ll rarely see a bug open for more than 24 hours after it’s reported. We do our best to answer all questions. Enhancements/suggestions are implemented on a best effort basis.

Fell free to submit your contribution via pull requests. Any little bit is appreciated, from improvements on documentation to a full blown rewrite from scratch.

For commercial support, customizations or anything in between, please contact support@univocity.com.

Thank you for using our parsers!

The univocity team.