com.devexperts.io

Class CSVReader

java.lang.Object

com.devexperts.io.CSVReader

All Implemented Interfaces:

Closeable, AutoCloseable

public class CSVReader
extends Object
implements Closeable

Reads data from the stream using Comma-Separated Values (CSV) format. See RFC 4180 for CSV format specification.

This reader supports records with arbitrary (variable) number of fields, multiline fields, custom separator and quote characters. It accepts CR, LF and CRLF sequence as record separators.

This reader provides its own buffering but does not perform decoding. The correct way to efficiently read CSV file with UTF-8 encoding is as follows:

 CSVReader reader = new CSVReader(new InputStreamReader(new FileInputStream(file), StandardCharsets.UTF_8));
 String[] header = reader.readRecord();
 List<String[]> records = reader.readAll();
 reader.close();
 

Constructor Summary

Constructors

Constructor and Description
CSVReader(Reader reader) Creates new CSVReader with default separator and quote characters.
CSVReader(Reader reader, char separator, char quote) Creates new CSVReader with specified separator and quote characters.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the stream.
int	getLineNumber() Returns current line number.
int	getRecordNumber() Returns current record number.
boolean	isRecordEnded() Returns true if record has ended.
List<String[]>	readAll() Reads and returns all records or empty list if stream has ended.
String	readField() Reads and returns a single field of the current record or null if record has ended.
String	readField(String expectedFieldValue) Reads and returns a single field of the current record or null if record has ended.
String[]	readRecord() Reads and returns a remaining fields of the current record or null if stream has ended.
int	readRecord(List<String> fields) Reads and returns the number of remaining fields of the current record or -1 if stream has ended.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CSVReader

public CSVReader(Reader reader)

Creates new CSVReader with default separator and quote characters.

Throws:

NullPointerException - if reader is null

CSVReader

public CSVReader(Reader reader,
                 char separator,
                 char quote)

Creates new CSVReader with specified separator and quote characters.

Throws:

NullPointerException - if reader is null

IllegalArgumentException - if separator or quote characters are invalid

Method Detail

getLineNumber

public int getLineNumber()

Returns current line number. Line numeration starts with 1 and counts new lines within record fields. Both CR and LF are counted as new lines, although CRLF sequence is counted only once. Line number points to new line after completion of the current record.

getRecordNumber

public int getRecordNumber()

Returns current record number. Record numeration starts with 1 and does not count new lines within record fields. Record number points to new record after completion of the current record.

isRecordEnded

public boolean isRecordEnded()

Returns true if record has ended.

readField

public String readField()
                 throws IOException

Reads and returns a single field of the current record or null if record has ended. Returns empty string if field is empty.

This method does not advance to the next record - it keeps to return null.

Throws:

CSVFormatException - if input stream does not conform to the CSV format

IOException - If an I/O error occurs

readField

public String readField(String expectedFieldValue)
                 throws IOException

Reads and returns a single field of the current record or null if record has ended. Returns empty string if field is empty. Returns specified expectedFieldValue string if it is equal to actual field value.

This method does not advance to the next record - it keeps to return null.

Parameters:

expectedFieldValue - expected field value

Throws:

NullPointerException - if expectedFieldValue is null

CSVFormatException - if input stream does not conform to the CSV format

IOException - If an I/O error occurs

readRecord

public String[] readRecord()
                    throws IOException

Reads and returns a remaining fields of the current record or null if stream has ended. Returns empty array (length 0) if all record fields were already read by readField() method. Returns array of length 1 with single empty string if record is empty (empty line). Returns empty strings for those fields that are empty.

This method advances to the next record upon completion.

Throws:

CSVFormatException - if input stream does not conform to the CSV format

IOException - If an I/O error occurs

readRecord

public int readRecord(List<String> fields)
               throws IOException

Reads and returns the number of remaining fields of the current record or -1 if stream has ended. Returns 0 if all record fields were already read by readField() method. Returns 1 (and a single empty string in fields list) if record is empty (empty line). Returns empty strings for those fields that are empty.

This method uses specified fields list both as a source of expected fields values and as a destination for actual field values. Specifically, when reading n^th field it uses n^th string from the list as expected field value and stores actual field value to the n^th position in the list. This method grows specified field list as needed but it never shrinks it, thus the list keeps old strings beyond actual returned record size.

This method advances to the next record upon completion.

Parameters:

fields - list of expected field values prior invocation and list of actual field values afterwards

Returns:

number of actual fields in the record or -1 if stream has ended

Throws:

CSVFormatException - if input stream does not conform to the CSV format

IOException - If an I/O error occurs

readAll

public List<String[]> readAll()
                       throws IOException

Reads and returns all records or empty list if stream has ended. Empty records are represented by arrays of length 1 with single empty string. Empty fields are represented by empty strings.

Throws:

CSVFormatException - if input stream does not conform to the CSV format

IOException - If an I/O error occurs

close

public void close()
           throws IOException

Closes the stream.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - If an I/O error occurs