Class CsvReader<T>

java.lang.Object
de.siegmar.fastcsv.reader.CsvReader<T>
Type Parameters:
T - the type of the CSV record.
All Implemented Interfaces:
Closeable, AutoCloseable, Iterable<T>
public final class CsvReader<T> extends Object implements Iterable<T>, Closeable

This is the main class for reading CSV data.

The CSV records are read iteratively, regardless of whether the Iterable, the Iterator, or the Stream is used. Once all records are read, the data is consumed. If you need to repeatedly read records, you should collect the records in a List or another collection.

This class is not thread-safe and must not be shared between threads.

Exception handling:

  • IOException is thrown by file/path-based build methods if the file cannot be opened.
  • UncheckedIOException wraps I/O errors that occur during iteration or streaming.
  • CsvParseException signals structural CSV errors (e.g., malformed quoting, field count mismatch, or exceeded size limits).

Example use:

try (CsvReader<CsvRecord> csv = CsvReader.builder().ofCsvRecord(file)) {
    for (CsvRecord csvRecord : csv) {
        // ...
    }
}

Example for named records:

try (CsvReader<NamedCsvRecord> csv = CsvReader.builder().ofNamedCsvRecord(file)) {
    for (NamedCsvRecord csvRecord : csv) {
        // ...
    }
}

  • Method Details

    • builder

      public static CsvReader.CsvReaderBuilder builder()
      Constructs a CsvReader.CsvReaderBuilder to configure and build instances of this class.
      Returns:
      a new CsvReader.CsvReaderBuilder instance.

    • skipLines

      public void skipLines(int lineCount)

      Skips the specified number of lines.

      Note: "lines" here means physical lines terminated by CR, LF, or CRLF — not CSV records. A non-empty final segment that is not terminated by a line break (for example, the last line of a file without a trailing newline) is also counted as one line. This method is intended for skipping non-CSV preamble lines that appear before the actual CSV data starts and must therefore be called before any records are read; once iteration has begun this method throws IllegalStateException.

      The setting CsvReader.CsvReaderBuilder.skipEmptyLines(boolean) has no effect on this method.

      Parameters:
      lineCount - the number of lines to skip.
      Throws:
      IllegalArgumentException - if lineCount is negative.
      IllegalStateException - if any CSV records have already been read.
      UncheckedIOException - if an I/O error occurs.
      CsvParseException - unless enough lines are available to skip.

    • skipLines

      public int skipLines(Predicate<String> predicate, int maxLines)

      Skip lines until the specified predicate matches. The line that matches the predicate is not skipped.

      The method returns the number of lines actually skipped.

      Note: "lines" here means physical lines terminated by CR, LF, or CRLF — not CSV records. A non-empty final segment that is not terminated by a line break (for example, the last line of a file without a trailing newline) is also counted as one line. The predicate sees each physical line as a plain string, with no awareness of quoting or escaping. This method is intended for skipping non-CSV preamble lines that appear before the actual CSV data starts and must therefore be called before any records are read; once iteration has begun this method throws IllegalStateException.

      The setting CsvReader.CsvReaderBuilder.skipEmptyLines(boolean) has no effect on this method.

      Parameters:
      predicate - the predicate to match the lines.
      maxLines - the maximum number of lines to skip.
      Returns:
      the number of lines actually skipped.
      Throws:
      NullPointerException - if predicate is null.
      IllegalArgumentException - if maxLines is negative.
      IllegalStateException - if any CSV records have already been read.
      UncheckedIOException - if an I/O error occurs.
      CsvParseException - if no matching line is found within the maximum limit of maxLines.

    • iterator

      public CloseableIterator<T> iterator()

      Returns an iterator over elements of type CsvRecord..

      The returned iterator is not thread-safe. Remember to close the returned iterator when you're done. Alternatively, use stream().

      This method is idempotent and can be called multiple times.

      Specified by:
      iterator in interface Iterable<T>
      Returns:
      an iterator over elements of type CsvRecord.
      Throws:
      UncheckedIOException - if an I/O error occurs.
      CsvParseException - if any other problem occurs when parsing the CSV data.
      See Also:

    • spliterator

      public Spliterator<T> spliterator()

      Constructs a Spliterator for splitting and traversing the elements of this reader.

      The returned spliterator is not thread-safe. Remember to invoke close() when you're done. Alternatively, use stream().

      This method is idempotent and can be called multiple times.

      Specified by:
      spliterator in interface Iterable<T>
      Returns:
      a spliterator over the CSV records.
      Throws:
      UncheckedIOException - if an I/O error occurs.
      CsvParseException - if any other problem occurs when parsing the CSV data.
      See Also:

    • stream

      public Stream<T> stream()

      Constructs a new sequential Stream with this reader as its source.

      The returned stream is not thread-safe. Remember to close the returned stream when you're done. Closing the stream will also close this reader.

      This method can be called multiple times, although it creates a new stream each time.

      The stream is not reusable after it has been closed.

      Returns:
      a sequential Stream over the CSV records.
      Throws:
      UncheckedIOException - if an I/O error occurs.
      CsvParseException - if any other problem occurs when parsing the CSV data.
      See Also:

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • toString

      public String toString()
      Overrides:
      toString in class Object