feat: lock skipLines once CSV parsing has started

skipLines(int) and skipLines(Predicate, int) operate on physical
lines and are intended for skipping non-CSV preamble before the
actual CSV data starts. Calling them after iteration has begun
can split a quoted field at an embedded newline and corrupt the
parser's view of subsequent records.

Track whether parsing has started (set in fetchRecord before the
first parse() call) and throw IllegalStateException from both
skipLines overloads if invoked after that point. Document the
throw contract on both methods.

No existing test calls skipLines after iteration starts, so this
is a tightening rather than a behaviour change for any documented
use case.

JMH: FastCsvReadBenchmark and FastCsvReadRelaxedBenchmark unchanged
within noise.

Author: osiegmar

lib/src/intTest/java/blackbox/reader/AbstractSkipLinesTest.java

@@ -299,6 +299,24 @@ void predicateIoException() {
             .hasMessage("java.io.IOException: Cannot read");
     }
 
+    @Test
+    void skipLinesCountAfterIterationStartedThrows() {
+        final CsvReader<CsvRecord> csv = crb.ofCsvRecord("a\nb\nc");
+        assertThat(csv.iterator()).hasNext();
+        assertThatThrownBy(() -> csv.skipLines(1))
+            .isInstanceOf(IllegalStateException.class)
+            .hasMessage("skipLines must be called before any CSV records are read");
+    }
+
+    @Test
+    void skipLinesPredicateAfterIterationStartedThrows() {
+        final CsvReader<CsvRecord> csv = crb.ofCsvRecord("a\nb\nc");
+        assertThat(csv.iterator()).hasNext();
+        assertThatThrownBy(() -> csv.skipLines(_ -> true, 1))
+            .isInstanceOf(IllegalStateException.class)
+            .hasMessage("skipLines must be called before any CSV records are read");
+    }
+
     @Test
     void predicateNotCalledForEmptyLine() {
         final Predicate<String> p = line -> {

lib/src/main/java/de/siegmar/fastcsv/reader/CsvReader.java

@@ -68,6 +68,7 @@ public final class CsvReader<T> implements Iterable<T>, Closeable {
     private final CloseableIterator<T> csvRecordIterator = new CsvRecordIterator();
 
     private int firstRecordFieldCount = -1;
+    private boolean parsingStarted;
 
     @SuppressWarnings("checkstyle:ParameterNumber")
     CsvReader(final CsvParser csvParser, final CsvCallbackHandler<T> callbackHandler,
@@ -95,16 +96,26 @@ public static CsvReaderBuilder builder() {
 
     /// Skips the specified number of lines.
     ///
+    /// **Note:** "lines" here means *physical* lines terminated by `CR`, `LF`, or `CRLF` —
+    /// not CSV records. 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 [CsvReaderBuilder#skipEmptyLines(boolean)] has no effect on this method.
     ///
     /// @param lineCount the number of lines to skip.
     /// @throws IllegalArgumentException if lineCount is negative.
+    /// @throws IllegalStateException    if any CSV records have already been read.
     /// @throws UncheckedIOException     if an I/O error occurs.
     /// @throws CsvParseException        unless enough lines are available to skip.
     public void skipLines(final int lineCount) {
         if (lineCount < 0) {
             throw new IllegalArgumentException("lineCount must be non-negative");
         }
+        if (parsingStarted) {
+            throw new IllegalStateException("skipLines must be called before any CSV records are read");
+        }
 
         int i = 0;
         try {
@@ -123,20 +134,31 @@ public void skipLines(final int lineCount) {
     ///
     /// The method returns the number of lines actually skipped.
     ///
+    /// **Note:** "lines" here means *physical* lines terminated by `CR`, `LF`, or `CRLF` —
+    /// not CSV records. 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 [CsvReaderBuilder#skipEmptyLines(boolean)] has no effect on this method.
     ///
     /// @param predicate the predicate to match the lines.
     /// @param maxLines  the maximum number of lines to skip.
     /// @return the number of lines actually skipped.
     /// @throws NullPointerException if predicate is `null`.
     /// @throws IllegalArgumentException if maxLines is negative.
+    /// @throws IllegalStateException if any CSV records have already been read.
     /// @throws UncheckedIOException if an I/O error occurs.
     /// @throws CsvParseException if no matching line is found within the maximum limit of maxLines.
     public int skipLines(final Predicate<String> predicate, final int maxLines) {
         Objects.requireNonNull(predicate, "predicate must not be null");
         if (maxLines < 0) {
             throw new IllegalArgumentException("maxLines must be non-negative");
         }
+        if (parsingStarted) {
+            throw new IllegalStateException("skipLines must be called before any CSV records are read");
+        }
 
         if (maxLines == 0) {
             return 0;
@@ -222,6 +244,7 @@ public Stream<T> stream() {
 
     @Nullable
     private T fetchRecord() throws IOException {
+        parsingStarted = true;
         while (csvParser.parse()) {
             final T csvRecord = processRecord();