CSVParser (Apache Commons CSV 1.14.1 API)
Description: declaration: package: org.apache.commons.csv, class: CSVParser

Package org.apache.commons.csv

# Class CSVParser

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:

- `parse(java.io.File, Charset, CSVFormat)`
- `parse(String, CSVFormat)`
- `parse(java.net.URL, java.nio.charset.Charset, CSVFormat)`

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 hand, custom formats can be defined. More information about customizing 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

The internal parser state is completely covered by the format and the reader state.

See Also:
  - package documentation for more details

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `CSVParser.Builder`
  Builds a new `CSVParser`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CSVParser(Reader reader, CSVFormat format)`
  Deprecated.
  Will be removed in the next major version, use `CSVParser.Builder.get()`.
  `CSVParser(Reader reader, CSVFormat format, long characterOffset, long recordNumber)`
  Deprecated.
  Will be removed in the next major version, use `CSVParser.Builder.get()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static CSVParser.Builder`
  `builder()`
  Creates a new builder.
  `void`
  `close()`
  Closes resources.
  `long`
  `getCurrentLineNumber()`
  Gets the current line number in the input stream.
  `String`
  `getFirstEndOfLine()`
  Gets the first end-of-line string encountered.
  `String`
  `getHeaderComment()`
  Gets the header comment, if any.
  `Map<String,Integer>`
  `getHeaderMap()`
  Gets a copy of the header map as defined in the CSVFormat's header.
  `List<String>`
  `getHeaderNames()`
  Gets a read-only list of header names that iterates in column order as defined in the CSVFormat's header.
  `long`
  `getRecordNumber()`
  Gets 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`.
  `String`
  `getTrailerComment()`
  Gets the trailer comment, if any.
  `boolean`
  `hasHeaderComment()`
  Checks whether there is a header comment.
  `boolean`
  `hasTrailerComment()`
  Checks whether there is a trailer comment.
  `boolean`
  `isClosed()`
  Tests whether this parser is closed.
  `Iterator<CSVRecord>`
  `iterator()`
  Returns the record iterator.
  `static CSVParser`
  `parse(File file, Charset charset, CSVFormat format)`
  Creates a parser for the given `File`.
  `static CSVParser`
  `parse(InputStream inputStream, Charset charset, CSVFormat format)`
  Creates a CSV parser using the given `CSVFormat`.
  `static CSVParser`
  `parse(Reader reader, CSVFormat format)`
  Creates a CSV parser using the given `CSVFormat`
  `static CSVParser`
  `parse(String string, CSVFormat format)`
  Creates a parser for the given `String`.
  `static CSVParser`
  `parse(URL url, Charset charset, CSVFormat format)`
  Creates and returns a parser for the given URL, which the caller MUST close.
  `static CSVParser`
  `parse(Path path, Charset charset, CSVFormat format)`
  Creates and returns a parser for the given `Path`, which the caller MUST close.
  `Stream<CSVRecord>`
  `stream()`
  Returns a sequential `Stream` with this collection as its source.

  ### 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 Details

  - ### CSVParser

    @Deprecated public CSVParser(Reader reader, CSVFormat format) throws IOException
    Deprecated.
    Will be removed in the next major version, use `CSVParser.Builder.get()`.
    Constructs a new instance 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
      `CSVException` - Thrown on invalid CSV input data.

  - ### CSVParser

    @Deprecated public CSVParser(Reader reader, CSVFormat format, long characterOffset, long recordNumber) throws IOException
    Deprecated.
    Will be removed in the next major version, use `CSVParser.Builder.get()`.
    Constructs a new instance 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 the reader or format is null.
      `IOException` - if there is a problem reading the header or skipping the first record
      `CSVException` - on invalid input.
    Since:
      1.1

- ## Method Details

  - ### builder

    public static CSVParser.Builder builder()
    Creates a new builder.
    Returns:
      a new builder.
    Since:
      1.13.0

  - ### parse

    public static CSVParser parse(File file, Charset charset, CSVFormat format) throws IOException
    Creates a parser for the given `File`.
    Parameters:
      `file` - a CSV file. Must not be null.
      `charset` - The Charset to decode the given file, `null` maps to the `default Charset`.
      `format` - the CSVFormat used for CSV parsing, `null` maps to `CSVFormat.DEFAULT`.
    Returns:
      a new parser
    Throws:
      `IllegalArgumentException` - If the parameters of the format are inconsistent.
      `IOException` - If an I/O error occurs
      `CSVException` - Thrown on invalid CSV input data.
      `NullPointerException` - if `file` is `null`.

  - ### parse

    public static CSVParser parse(InputStream inputStream, Charset charset, CSVFormat format) throws IOException
    Creates a 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:
      `inputStream` - an InputStream containing CSV-formatted input, `null` maps to `CSVFormat.DEFAULT`.
      `charset` - The Charset to decode the given file, `null` maps to the `default Charset`.
      `format` - the CSVFormat used for CSV parsing, `null` maps to `CSVFormat.DEFAULT`.
    Returns:
      a new CSVParser configured with the given reader and format.
    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
      `CSVException` - Thrown on invalid CSV input data.
    Since:
      1.5

  - ### parse

    public static CSVParser parse(Path path, Charset charset, CSVFormat format) throws IOException
    Creates and returns a parser for the given `Path`, which the caller MUST close.
    Parameters:
      `path` - a CSV file. Must not be null.
      `charset` - The Charset to decode the given file, `null` maps to the `default Charset`.
      `format` - the CSVFormat used for CSV parsing, `null` maps to `CSVFormat.DEFAULT`.
    Returns:
      a new parser
    Throws:
      `IllegalArgumentException` - If the parameters of the format are inconsistent.
      `IOException` - If an I/O error occurs
      `CSVException` - Thrown on invalid CSV input data.
      `NullPointerException` - if `path` is `null`.
    Since:
      1.5

  - ### parse

    public static CSVParser parse(Reader reader, CSVFormat format) throws IOException
    Creates a 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, `null` maps to `CSVFormat.DEFAULT`.
    Returns:
      a new CSVParser configured with the given reader and format.
    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
      `CSVException` - Thrown on invalid CSV input data.
    Since:
      1.5

  - ### 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, `null` maps to `CSVFormat.DEFAULT`.
    Returns:
      a new parser
    Throws:
      `IllegalArgumentException` - If the parameters of the format are inconsistent.
      `IOException` - If an I/O error occurs
      `CSVException` - Thrown on invalid CSV input data.
      `NullPointerException` - if `string` is `null`.

  - ### parse

    public static CSVParser parse(URL url, Charset charset, CSVFormat format) throws IOException
    Creates and returns a parser for the given URL, which the caller MUST close.

    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, `null` maps to the `default Charset`.
      `format` - the CSVFormat used for CSV parsing, `null` maps to `CSVFormat.DEFAULT`.
    Returns:
      a new parser
    Throws:
      `IllegalArgumentException` - If the parameters of the format are inconsistent.
      `IOException` - If an I/O error occurs
      `CSVException` - Thrown on invalid CSV input data.
      `NullPointerException` - if `url` is `null`.

  - ### close

    public void close() throws IOException
    Closes resources.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Throws:
      `IOException` - If an I/O error occurs

  - ### getCurrentLineNumber

    public long getCurrentLineNumber()
    Gets the current line number in the input stream.

    Note: If your CSV input has multi-line values, the returned number does not correspond to the record number.

    Returns:
      current line number.

  - ### getFirstEndOfLine

    public String getFirstEndOfLine()
    Gets the first end-of-line string encountered.
    Returns:
      the first end-of-line string.
    Since:
      1.5

  - ### getHeaderComment

    public String getHeaderComment()
    Gets the header comment, if any. The header comment appears before the header record.
    Returns:
      the header comment for this stream, or null if no comment is available.
    Since:
      1.10.0

  - ### getHeaderMap

    public Map<String,Integer> getHeaderMap()
    Gets a copy of the header map as defined in the CSVFormat's header.

    The map keys are column names. The map values are 0-based indices.

    Note: The map can only provide a one-to-one mapping when the format did not contain null or duplicate column names.

    Returns:
      a copy of the header map.

  - ### getHeaderNames

    public List<String> getHeaderNames()
    Gets a read-only list of header names that iterates in column order as defined in the CSVFormat's header.

    Note: The list provides strings that can be used as keys in the header map. The list will not contain null column names if they were present in the input format.

    Returns:
      read-only list of header names that iterates in column order.
    Since:
      1.7
    See Also:
      - `getHeaderMap()`

  - ### getRecordNumber

    public long getRecordNumber()
    Gets the current record number in the input stream.

    Note: 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()
    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.

    You can use `CSVFormat.Builder.setMaxRows(long)` to limit how many rows this method produces.

    Returns:
      list of `CSVRecords`, may be empty
    Throws:
      `UncheckedIOException` - on parse error or input read-failure

  - ### getTrailerComment

    public String getTrailerComment()
    Gets the trailer comment, if any. Trailer comments are located between the last record and EOF
    Returns:
      the trailer comment for this stream, or null if no comment is available.
    Since:
      1.10.0

  - ### hasHeaderComment

    public boolean hasHeaderComment()
    Checks whether there is a header comment. The header comment appears before the header record. Note that if the parser's format has been given an explicit header (with `CSVFormat.Builder.setHeader(String...)` or another overload) and the header record is not being skipped (`CSVFormat.Builder.setSkipHeaderRecord(boolean)` is false) then any initial comments will be associated with the first record, not the header.
    Returns:
      true if this parser has seen a header comment, false otherwise
    Since:
      1.10.0

  - ### hasTrailerComment

    public boolean hasTrailerComment()
    Checks whether there is a trailer comment. Trailer comments are located between the last record and EOF. The trailer comments will only be available after the parser has finished processing this stream.
    Returns:
      true if this parser has seen a trailer comment, false otherwise
    Since:
      1.10.0

  - ### isClosed

    public boolean isClosed()
    Tests whether this parser is closed.
    Returns:
      whether this parser is closed.

  - ### iterator

    public Iterator<CSVRecord> iterator()
    Returns the record iterator.

    An `IOException` caught during the iteration is re-thrown as an `IllegalStateException`.

    If the parser is closed, the iterator will not yield any more records. A call to `Iterator.hasNext()` will return `false` and a call to `Iterator.next()` will throw a `NoSuchElementException`.

    If it is necessary to construct an iterator which is usable after the parser is closed, one option is to extract all records as a list with `getRecords()`, and return an iterator to that list.

    You can use `CSVFormat.Builder.setMaxRows(long)` to limit how many rows an Iterator produces.

    Specified by:
      `iterator` in interface `Iterable<CSVRecord>`

  - ### stream

    public Stream<CSVRecord> stream()
    Returns a sequential `Stream` with this collection as its source.

    If the parser is closed, the stream will not produce any more values. See the comments in `iterator()`.

    You can use `CSVFormat.Builder.setMaxRows(long)` to limit how many rows a Stream produces.

    Returns:
      a sequential `Stream` with this collection as its source.
    Since:
      1.9.0