CSVParser (Apache Commons CSV 1.1 API)

java.lang.Object
-
- org.apache.commons.csv.CSVParser
-

-
-
All Implemented Interfaces:
-
Closeable, AutoCloseable, Iterable<CSVRecord>
-
-
-
-
```
public final class CSVParser
-extends Object
-implements Iterable<CSVRecord>, Closeable
```
-
Parses CSV files according to the specified format. - - Because CSV appears in many different dialects, the parser supports many formats by allowing the - specification of a CSVFormat. - - The parser works record wise. It is not possible to go back, once a record has been parsed from the input stream. - -
Creating instances
-
- There are several static factory methods that can be used to create instances for various types of resources: -
-
-
- Alternatively parsers can also be created by passing a Reader directly to the sole constructor. - - For those who like fluent APIs, parsers can be created using CSVFormat.parse(java.io.Reader) as a shortcut: -
-
```
- for(CSVRecord record : CSVFormat.EXCEL.parse(in)) {
-     ...
- }
- 
```
- -
Parsing record wise
-
- To parse a CSV input from a file, you write: -
- -
```
- File csvData = new File("/path/to/csv");
- CSVParser parser = CSVParser.parse(csvData, CSVFormat.RFC4180);
- for (CSVRecord csvRecord : parser) {
-     ...
- }
- 
```
- -
- This will read the parse the contents of the file using the - RFC 4180 format. -
- -
- To parse CSV input in a format like Excel, you write: -
- -
```
- CSVParser parser = CSVParser.parse(csvData, CSVFormat.EXCEL);
- for (CSVRecord csvRecord : parser) {
-     ...
- }
- 
```
- -
- If the predefined formats don't match the format at hands, custom formats can be defined. More information about - customising CSVFormats is available in CSVFormat JavaDoc. -
- -
Parsing into memory
-
- If parsing record wise is not desired, the contents of the input can be read completely into memory. -
- -
```
- Reader in = new StringReader("a;b\nc;d");
- CSVParser parser = new CSVParser(in, CSVFormat.EXCEL);
- List<CSVRecord> list = parser.getRecords();
- 
```
- -
- There are two constraints that have to be kept in mind: -
- -
1. Parsing into memory starts at the current position of the parser. If you have already parsed records from - the input, those records will not end up in the in memory representation of your CSV data.
2. Parsing into memory may consume a lot of system resources depending on the input. For example if you're - parsing a 150MB file of CSV data the contents will be read completely into memory.
- -
Notes
-
- Internal parser state is completely covered by the format and the reader-state. -
-
-
Version:
-
$Id: CSVParser.java 1637611 2014-11-08 23:38:48Z ggregory $
-
See Also:
-
package documentation for more details
-
-

- -

Constructor Summary

- - - - - - - - - - - -

Constructors
Constructor and Description
`CSVParser(Reader reader, - CSVFormat format)` - Customized CSV parser using the given `CSVFormat` -
`CSVParser(Reader reader, - CSVFormat format, - long characterOffset, - long recordNumber)` - Customized CSV parser using the given `CSVFormat` -

- -

- - -

Method Summary

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close()` - Closes resources. -
`long`	`getCurrentLineNumber()` - Returns the current line number in the input stream. -
`Map<String,Integer>`	`getHeaderMap()` - Returns a copy of the header map that iterates in column order. -
`long`	`getRecordNumber()` - Returns the current record number in the input stream. -
`List<CSVRecord>`	`getRecords()` - Parses the CSV input according to the given format and returns the content as a list of - `CSVRecords`. -
`boolean`	`isClosed()` - Gets whether this parser is closed. -
`Iterator<CSVRecord>`	`iterator()` - Returns an iterator on the records. -
`static CSVParser`	`parse(File file, - Charset charset, - CSVFormat format)` - Creates a parser for the given `File`. -
`static CSVParser`	`parse(String string, - CSVFormat format)` - Creates a parser for the given `String`. -
`static CSVParser`	`parse(URL url, - Charset charset, - CSVFormat format)` - Creates a parser for the given URL. -

- - -
Methods inherited from class java.lang.Object
-clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- - -
Methods inherited from interface java.lang.Iterable
-forEach, spliterator

- -
- - - -
  Constructor Detail
  - - - -
  - -
    CSVParser
    -
```
public CSVParser(Reader reader,
-                 CSVFormat format)
-          throws IOException
```
    -
    Customized CSV parser using the given CSVFormat - -
    - If you do not read all records from the given reader, you should call close() on the parser, - unless you close the reader. -
    -
    -
    Parameters:
    -
    reader - a Reader containing CSV-formatted input. Must not be null.
    -
    format - the CSVFormat used for CSV parsing. Must not be null.
    -
    Throws:
    -
    IllegalArgumentException - If the parameters of the format are inconsistent or if either reader or format are null.
    -
    IOException - If there is a problem reading the header or skipping the first record
    -
    -
  - - - -
  - -
    CSVParser
    -
```
public CSVParser(Reader reader,
-                 CSVFormat format,
-                 long characterOffset,
-                 long recordNumber)
-          throws IOException
```
    -
    Customized CSV parser using the given CSVFormat - -
    - If you do not read all records from the given reader, you should call close() on the parser, - unless you close the reader. -
    -
    -
    Parameters:
    -
    reader - a Reader containing CSV-formatted input. Must not be null.
    -
    format - the CSVFormat used for CSV parsing. Must not be null.
    -
    characterOffset - Lexer offset when the parser does not start parsing at the beginning of the source.
    -
    recordNumber - The next record number to assign
    -
    Throws:
    -
    IllegalArgumentException - If the parameters of the format are inconsistent or if either reader or format are null.
    -
    IOException - If there is a problem reading the header or skipping the first record
    -
    Since:
    -
    1.1
    -
    -
  -
- -
- - - -
  Method Detail
  - - - -
  - -
    parse
    -
```
public static CSVParser parse(File file,
-                              Charset charset,
-                              CSVFormat format)
-                       throws IOException
```
    -
    Creates a parser for the given File. - -
    Note: This method internally creates a FileReader using - FileReader.FileReader(java.io.File) which in turn relies on the default encoding of the JVM that - is executing the code. If this is insufficient create a URL to the file and use - parse(URL, Charset, CSVFormat)
    -
    -
    Parameters:
    -
    file - a CSV file. Must not be null.
    -
    charset - A charset
    -
    format - the CSVFormat used for CSV parsing. Must not be null.
    -
    Returns:
    -
    a new parser
    -
    Throws:
    -
    IllegalArgumentException - If the parameters of the format are inconsistent or if either file or format are null.
    -
    IOException - If an I/O error occurs
    -
    -
  - - - -
  - -
    parse
    -
```
public static CSVParser parse(String string,
-                              CSVFormat format)
-                       throws IOException
```
    -
    Creates a parser for the given String.
    -
    -
    Parameters:
    -
    string - a CSV string. Must not be null.
    -
    format - the CSVFormat used for CSV parsing. Must not be null.
    -
    Returns:
    -
    a new parser
    -
    Throws:
    -
    IllegalArgumentException - If the parameters of the format are inconsistent or if either string or format are null.
    -
    IOException - If an I/O error occurs
    -
    -
  - - - -
  - -
    parse
    -
```
public static CSVParser parse(URL url,
-                              Charset charset,
-                              CSVFormat format)
-                       throws IOException
```
    -
    Creates a parser for the given URL. - -
    - If you do not read all records from the given url, you should call close() on the parser, unless - you close the url. -
    -
    -
    Parameters:
    -
    url - a URL. Must not be null.
    -
    charset - the charset for the resource. Must not be null.
    -
    format - the CSVFormat used for CSV parsing. Must not be null.
    -
    Returns:
    -
    a new parser
    -
    Throws:
    -
    IllegalArgumentException - If the parameters of the format are inconsistent or if either url, charset or format are null.
    -
    IOException - If an I/O error occurs
    -
    -
  - - - -
  - -
    close
    -
```
public void close()
-           throws IOException
```
    -
    Closes resources.
    -
    -
    Specified by:
    -
    close in interface Closeable
    -
    Specified by:
    -
    close in interface AutoCloseable
    -
    Throws:
    -
    IOException - If an I/O error occurs
    -
    -
  - - - -
  - -
    getCurrentLineNumber
    -
```
public long getCurrentLineNumber()
```
    -
    Returns the current line number in the input stream. - -
    - ATTENTION: If your CSV input has multi-line values, the returned number does not correspond to - the record number. -
    -
    -
    Returns:
    -
    current line number
    -
    -
  - - - -
  - -
    getHeaderMap
    -
```
public Map<String,Integer> getHeaderMap()
```
    -
    Returns a copy of the header map that iterates in column order. -
    - The map keys are column names. The map values are 0-based indices. -
    -
    -
    Returns:
    -
    a copy of the header map that iterates in column order.
    -
    -
  - - - -
  - -
    getRecordNumber
    -
```
public long getRecordNumber()
```
    -
    Returns the current record number in the input stream. - -
    - ATTENTION: If your CSV input has multi-line values, the returned number does not correspond to - the line number. -
    -
    -
    Returns:
    -
    current record number
    -
    -
  - - - -
  - -
    getRecords
    -
```
public List<CSVRecord> getRecords()
-                           throws IOException
```
    -
    Parses the CSV input according to the given format and returns the content as a list of - CSVRecords. - -
    - The returned content starts at the current parse-position in the stream. -
    -
    -
    Returns:
    -
    list of CSVRecords, may be empty
    -
    Throws:
    -
    IOException - on parse error or input read-failure
    -
    -
  - - - -
  - -
    isClosed
    -
```
public boolean isClosed()
```
    -
    Gets whether this parser is closed.
    -
    -
    Returns:
    -
    whether this parser is closed.
    -
    -
  - - - -
  - -
    iterator
    -
```
public Iterator<CSVRecord> iterator()
```
    -
    Returns an iterator on the records. - -
    IOExceptions occurring during the iteration are wrapped in a - RuntimeException. - If the parser is closed a call to next() will throw a - NoSuchElementException.
    -
    -
    Specified by:
    -
    iterator in interface Iterable<CSVRecord>
    -
    -
  -
-

java.lang.Object
+
- org.apache.commons.csv.CSVParser
+

+
+
All Implemented Interfaces:
+
Closeable, AutoCloseable, Iterable<CSVRecord>
+
+
+
+
```
public final class CSVParser
+extends Object
+implements Iterable<CSVRecord>, Closeable
```
+
Parses CSV files according to the specified format. + + Because CSV appears in many different dialects, the parser supports many formats by allowing the + specification of a CSVFormat. + + The parser works record wise. It is not possible to go back, once a record has been parsed from the input stream. + +
Creating instances
+
+ There are several static factory methods that can be used to create instances for various types of resources: +
+
+
+ Alternatively parsers can also be created by passing a Reader directly to the sole constructor. + + For those who like fluent APIs, parsers can be created using CSVFormat.parse(java.io.Reader) as a shortcut: +
+
```
+ for(CSVRecord record : CSVFormat.EXCEL.parse(in)) {
+     ...
+ }
+ 
```
+ +
Parsing record wise
+
+ To parse a CSV input from a file, you write: +
+ +
```
+ File csvData = new File("/path/to/csv");
+ CSVParser parser = CSVParser.parse(csvData, CSVFormat.RFC4180);
+ for (CSVRecord csvRecord : parser) {
+     ...
+ }
+ 
```
+ +
+ This will read the parse the contents of the file using the + RFC 4180 format. +
+ +
+ To parse CSV input in a format like Excel, you write: +
+ +
```
+ CSVParser parser = CSVParser.parse(csvData, CSVFormat.EXCEL);
+ for (CSVRecord csvRecord : parser) {
+     ...
+ }
+ 
```
+ +
+ If the predefined formats don't match the format at hands, custom formats can be defined. More information about + customising CSVFormats is available in CSVFormat JavaDoc. +
+ +
Parsing into memory
+
+ If parsing record wise is not desired, the contents of the input can be read completely into memory. +
+ +
```
+ Reader in = new StringReader("a;b\nc;d");
+ CSVParser parser = new CSVParser(in, CSVFormat.EXCEL);
+ List<CSVRecord> list = parser.getRecords();
+ 
```
+ +
+ There are two constraints that have to be kept in mind: +
+ +
1. Parsing into memory starts at the current position of the parser. If you have already parsed records from + the input, those records will not end up in the in memory representation of your CSV data.
2. Parsing into memory may consume a lot of system resources depending on the input. For example if you're + parsing a 150MB file of CSV data the contents will be read completely into memory.
+ +
Notes
+
+ Internal parser state is completely covered by the format and the reader-state. +
+
Version:
+
$Id: CSVParser.java 1637611 2014-11-08 23:38:48Z ggregory $
+
See Also:
package documentation for more details
+

+ +

+ + +

Constructor Summary

+ + + + + + + + + + + +

Constructors
Constructor and Description
`CSVParser(Reader reader, + CSVFormat format)` + Customized CSV parser using the given `CSVFormat` + + + If you do not read all records from the given `reader`, you should call `close()` on the parser, + unless you close the `reader`. +
`CSVParser(Reader reader, + CSVFormat format, + long characterOffset, + long recordNumber)` + Customized CSV parser using the given `CSVFormat` + + + If you do not read all records from the given `reader`, you should call `close()` on the parser, + unless you close the `reader`. +

+ +

+ + +

Method Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Methods
Modifier and Type	Method and Description
`void`	`close()` + Closes resources. +
`long`	`getCurrentLineNumber()` + Returns the current line number in the input stream. +
`Map<String,Integer>`	`getHeaderMap()` + Returns a copy of the header map that iterates in column order. +
`long`	`getRecordNumber()` + Returns the current record number in the input stream. +
`List<CSVRecord>`	`getRecords()` + Parses the CSV input according to the given format and returns the content as a list of + `CSVRecords`. +
`boolean`	`isClosed()` + Gets whether this parser is closed. +
`Iterator<CSVRecord>`	`iterator()` + Returns an iterator on the records. +
`static CSVParser`	`parse(File file, + Charset charset, + CSVFormat format)` + Creates a parser for the given `File`. +
`static CSVParser`	`parse(String string, + CSVFormat format)` + Creates a parser for the given `String`. +
`static CSVParser`	`parse(URL url, + Charset charset, + CSVFormat format)` + Creates a parser for the given URL. +

+ + +
Methods inherited from class java.lang.Object
+clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

+ +
- + + +
  Constructor Detail
  + + + +
  - +
    CSVParser
    +
```
public CSVParser(Reader reader,
+         CSVFormat format)
+          throws IOException
```
    +
    Customized CSV parser using the given CSVFormat + +
    + If you do not read all records from the given reader, you should call close() on the parser, + unless you close the reader. +
    +
    Parameters:
    reader - a Reader containing CSV-formatted input. Must not be null.
    format - the CSVFormat used for CSV parsing. Must not be null.
    +
    Throws:
    +
    IllegalArgumentException - If the parameters of the format are inconsistent or if either reader or format are null.
    +
    IOException - If there is a problem reading the header or skipping the first record
    +
  + + + +
  - +
    CSVParser
    +
```
public CSVParser(Reader reader,
+         CSVFormat format,
+         long characterOffset,
+         long recordNumber)
+          throws IOException
```
    +
    Customized CSV parser using the given CSVFormat + +
    + If you do not read all records from the given reader, you should call close() on the parser, + unless you close the reader. +
    +
    Parameters:
    reader - a Reader containing CSV-formatted input. Must not be null.
    format - the CSVFormat used for CSV parsing. Must not be null.
    characterOffset - Lexer offset when the parser does not start parsing at the beginning of the source.
    recordNumber - The next record number to assign
    +
    Throws:
    +
    IllegalArgumentException - If the parameters of the format are inconsistent or if either reader or format are null.
    +
    IOException - If there is a problem reading the header or skipping the first record
    Since:
    +
    1.1
    +
  +
+ +
- + + +
  Method Detail
  + + + +
  - +
    parse
    +
```
public static CSVParser parse(File file,
+              Charset charset,
+              CSVFormat format)
+                       throws IOException
```
    +
    Creates a parser for the given File. + +
    Note: This method internally creates a FileReader using + FileReader.FileReader(java.io.File) which in turn relies on the default encoding of the JVM that + is executing the code. If this is insufficient create a URL to the file and use + parse(URL, Charset, CSVFormat)
    +
    Parameters:
    file - a CSV file. Must not be null.
    charset - A charset
    format - the CSVFormat used for CSV parsing. Must not be null.
    +
    Returns:
    a new parser
    +
    Throws:
    +
    IllegalArgumentException - If the parameters of the format are inconsistent or if either file or format are null.
    +
    IOException - If an I/O error occurs
    +
  + + + +
  - +
    parse
    +
```
public static CSVParser parse(String string,
+              CSVFormat format)
+                       throws IOException
```
    +
    Creates a parser for the given String.
    +
    Parameters:
    string - a CSV string. Must not be null.
    format - the CSVFormat used for CSV parsing. Must not be null.
    +
    Returns:
    a new parser
    +
    Throws:
    +
    IllegalArgumentException - If the parameters of the format are inconsistent or if either string or format are null.
    +
    IOException - If an I/O error occurs
    +
  + + + +
  - +
    parse
    +
```
public static CSVParser parse(URL url,
+              Charset charset,
+              CSVFormat format)
+                       throws IOException
```
    +
    Creates a parser for the given URL. + +
    + If you do not read all records from the given url, you should call close() on the parser, unless + you close the url. +
    +
    Parameters:
    url - a URL. Must not be null.
    charset - the charset for the resource. Must not be null.
    format - the CSVFormat used for CSV parsing. Must not be null.
    +
    Returns:
    a new parser
    +
    Throws:
    +
    IllegalArgumentException - If the parameters of the format are inconsistent or if either url, charset or format are null.
    +
    IOException - If an I/O error occurs
    +
  + + + +
  - +
    close
    +
```
public void close()
+           throws IOException
```
    +
    Closes resources.
    +
    +
    Specified by:
    +
    close in interface Closeable
    +
    Specified by:
    +
    close in interface AutoCloseable
    +
    Throws:
    +
    IOException - If an I/O error occurs
    +
  + + + +
  - +
    getCurrentLineNumber
    +
```
public long getCurrentLineNumber()
```
    +
    Returns the current line number in the input stream. + +
    + ATTENTION: If your CSV input has multi-line values, the returned number does not correspond to + the record number. +
    +
    Returns:
    current line number
    +
  + + + +
  - +
    getHeaderMap
    +
```
public Map<String,Integer> getHeaderMap()
```
    +
    Returns a copy of the header map that iterates in column order. +
    + The map keys are column names. The map values are 0-based indices. +
    +
    Returns:
    a copy of the header map that iterates in column order.
    +
  + + + +
  - +
    getRecordNumber
    +
```
public long getRecordNumber()
```
    +
    Returns the current record number in the input stream. + +
    + ATTENTION: If your CSV input has multi-line values, the returned number does not correspond to + the line number. +
    +
    Returns:
    current record number
    +
  + + + +
  - +
    getRecords
    +
```
public List<CSVRecord> getRecords()
+                           throws IOException
```
    +
    Parses the CSV input according to the given format and returns the content as a list of + CSVRecords. + +
    + The returned content starts at the current parse-position in the stream. +
    +
    Returns:
    list of CSVRecords, may be empty
    +
    Throws:
    +
    IOException - on parse error or input read-failure
    +
  + + + +
  - +
    isClosed
    +
```
public boolean isClosed()
```
    +
    Gets whether this parser is closed.
    +
    Returns:
    whether this parser is closed.
    +
  + + + +
  - +
    iterator
    +
```
public Iterator<CSVRecord> iterator()
```
    +
    Returns an iterator on the records. + +
    IOExceptions occurring during the iteration are wrapped in a + RuntimeException. + If the parser is closed a call to next() will throw a + NoSuchElementException.
    +
    +
    Specified by:
    +
    iterator in interface Iterable<CSVRecord>
    +
    +
  +
+

Class CSVParser

Creating instances

Parsing record wise

Parsing into memory

Notes

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Detail

CSVParser

CSVParser

Method Detail

parse

parse

parse

close

getCurrentLineNumber

getHeaderMap

getRecordNumber

getRecords

isClosed

iterator

Class CSVParser

Creating instances

Parsing record wise

Parsing into memory

Notes

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CSVParser

CSVParser

Method Detail

parse

parse

parse

close

getCurrentLineNumber

getHeaderMap

getRecordNumber

getRecords

isClosed

iterator