feat: add FieldMismatchStrategy to replace allowExtraFields/allowMissingFields

Introduce a FieldMismatchStrategy enum (STRICT, IGNORE, SKIP) that provides
fine-grained control over how records with mismatched field counts are handled.
SKIP silently drops non-conforming records, which was previously impossible
without manual filtering.

New builder methods: extraFieldStrategy() and missingFieldStrategy().
The old allowExtraFields(boolean) and allowMissingFields(boolean) methods
are deprecated (forRemoval) and delegate to the new API.

Closes #176

Author: osiegmar

docs/src/content/docs/architecture/interpretation.md

@@ -98,8 +98,8 @@ record. However, this is just an assumption. Field `value_c_2` does not even hav
 To ensure no misinterpretation, FastCSV does not allow extra or missing fields in a record by default.
 This means that the above example would result in a `CsvParseException` when reading it with FastCSV.
 
-However, this behavior can be changed by setting `CsvReaderBuilder.allowExtraFields(boolean)`
-and `CsvReaderBuilder.allowMissingFields(boolean)` to `true`.
+However, this behavior can be changed by setting `CsvReaderBuilder.extraFieldStrategy(FieldMismatchStrategy)`
+and `CsvReaderBuilder.missingFieldStrategy(FieldMismatchStrategy)` to `IGNORE` or `SKIP`.
 
 ### Empty lines
 

docs/src/content/docs/guides/Examples/skip-non-csv-head.mdx

@@ -24,7 +24,7 @@ The main problem with those files is:
 
 - When working with named fields, the very first line (`This is an example of a CSV file that contains`)
   would be interpreted as the actual header line.
-- An exception would be thrown unless the options `allowExtraFields(true)` is set, as some lines have
+- An exception would be thrown with the default `extraFieldStrategy(FieldMismatchStrategy.STRICT)`, as some lines have
   more fields than the first line.
 
 FastCSV comes with two features to handle such files:

docs/src/content/docs/guides/basic.md

@@ -52,8 +52,8 @@ CsvReader.builder()
     .commentStrategy(CommentStrategy.SKIP)
     .commentCharacter('#')
     .skipEmptyLines(true)
-    .allowExtraFields(false)
-    .allowMissingFields(false)
+    .extraFieldStrategy(FieldMismatchStrategy.STRICT)
+    .missingFieldStrategy(FieldMismatchStrategy.STRICT)
     .allowExtraCharsAfterClosingQuote(false)
     .detectBomHeader(false)
     .maxBufferSize(16777216);

docs/src/content/docs/guides/upgrading.md

@@ -34,13 +34,13 @@ As the default has changed, you may need to check your code and your desired beh
 
 FastCSV 4.x no longer ignores different field counts by default, ensuring that data is not misinterpreted.
 
-You can change this behavior by calling `allowExtraFields(true)` and `allowMissingFields(true)` in the `CsvReaderBuilder`.
+You can change this behavior by calling `extraFieldStrategy(FieldMismatchStrategy.IGNORE)` and `missingFieldStrategy(FieldMismatchStrategy.IGNORE)` in the `CsvReaderBuilder`.
 These methods provide more control over how to handle different field counts in CSV data than the previous (now removed) `ignoreDifferentFieldCount()` method.
 
 ```java title="Example"
 CsvReaderBuilder builder = CsvReader.builder()
-    .allowExtraFields(true)
-    .allowMissingFields(true);
+    .extraFieldStrategy(FieldMismatchStrategy.IGNORE)
+    .missingFieldStrategy(FieldMismatchStrategy.IGNORE);
 
 try (CsvReader<CsvRecord> csv = builder.ofCsvRecord(csvFile)) {
     // ...

example/src/main/java/ExampleCsvReaderWithFaultyData.java

@@ -1,5 +1,6 @@
 import de.siegmar.fastcsv.reader.CsvParseException;
 import de.siegmar.fastcsv.reader.CsvReader;
+import de.siegmar.fastcsv.reader.FieldMismatchStrategy;
 
 /// Example for reading CSV data with faulty (or ambiguous) data.
 ///
@@ -22,10 +23,17 @@ void main() {
         e.printStackTrace(System.out);
     }
 
-    IO.println("Reading data while not ignoring different field counts:");
+    IO.println("Reading data while ignoring different field counts:");
     CsvReader.builder()
-        .allowExtraFields(true)
-        .allowMissingFields(true)
+        .extraFieldStrategy(FieldMismatchStrategy.IGNORE)
+        .missingFieldStrategy(FieldMismatchStrategy.IGNORE)
+        .ofCsvRecord(data)
+        .forEach(IO::println);
+
+    IO.println("Reading data while skipping records with different field counts:");
+    CsvReader.builder()
+        .extraFieldStrategy(FieldMismatchStrategy.SKIP)
+        .missingFieldStrategy(FieldMismatchStrategy.SKIP)
         .ofCsvRecord(data)
         .forEach(IO::println);
 }

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

@@ -2,7 +2,6 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatCode;
-import static org.assertj.core.api.Assertions.assertThatNoException;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 import java.io.CharArrayReader;
@@ -29,6 +28,7 @@
 import de.siegmar.fastcsv.reader.CsvReader;
 import de.siegmar.fastcsv.reader.CsvRecord;
 import de.siegmar.fastcsv.reader.CsvRecordHandler;
+import de.siegmar.fastcsv.reader.FieldMismatchStrategy;
 import de.siegmar.fastcsv.reader.FieldModifiers;
 import testutil.CsvRecordAssert;
 
@@ -120,10 +120,11 @@ void immutableResponse() {
             .isInstanceOf(UnsupportedOperationException.class);
     }
 
-    // allow extra fields
+    // extra field strategy
 
     @Test
-    void allowNoExtraFields() {
+    void extraFieldStrategyStrict() {
+        crb.extraFieldStrategy(FieldMismatchStrategy.STRICT);
         assertThatThrownBy(() -> readAll("foo\nfoo,bar"))
             .isInstanceOf(CsvParseException.class)
             .hasMessage("Exception when reading record that started in line 2")
@@ -132,15 +133,34 @@ void allowNoExtraFields() {
     }
 
     @Test
-    void allowExtraFields() {
-        crb.allowExtraFields(true);
-        assertThatNoException().isThrownBy(() -> readAll("foo\nfoo,bar"));
+    void extraFieldStrategyIgnore() {
+        crb.extraFieldStrategy(FieldMismatchStrategy.IGNORE);
+        assertThat(readAll("foo\nfoo,bar"))
+            .satisfiesExactly(
+                item1 -> CsvRecordAssert.assertThat(item1)
+                    .fields().containsExactly("foo"),
+                item2 -> CsvRecordAssert.assertThat(item2)
+                    .fields().containsExactly("foo", "bar")
+            );
+    }
+
+    @Test
+    void extraFieldStrategySkip() {
+        crb.extraFieldStrategy(FieldMismatchStrategy.SKIP);
+        assertThat(readAll("foo\nfoo,bar\nbaz"))
+            .satisfiesExactly(
+                item1 -> CsvRecordAssert.assertThat(item1)
+                    .fields().containsExactly("foo"),
+                item2 -> CsvRecordAssert.assertThat(item2)
+                    .fields().containsExactly("baz")
+            );
     }
 
-    // allow missing fields
+    // missing field strategy
 
     @Test
-    void allowNoMissingFields() {
+    void missingFieldStrategyStrict() {
+        crb.missingFieldStrategy(FieldMismatchStrategy.STRICT);
         assertThatThrownBy(() -> readAll("foo,bar\nfoo"))
             .isInstanceOf(CsvParseException.class)
             .hasMessage("Exception when reading record that started in line 2")
@@ -149,9 +169,44 @@ void allowNoMissingFields() {
     }
 
     @Test
-    void allowMissingFields() {
-        crb.allowMissingFields(true);
-        assertThatNoException().isThrownBy(() -> readAll("foo,bar\nfoo"));
+    void missingFieldStrategyIgnore() {
+        crb.missingFieldStrategy(FieldMismatchStrategy.IGNORE);
+        assertThat(readAll("foo,bar\nfoo"))
+            .satisfiesExactly(
+                item1 -> CsvRecordAssert.assertThat(item1)
+                    .fields().containsExactly("foo", "bar"),
+                item2 -> CsvRecordAssert.assertThat(item2)
+                    .fields().containsExactly("foo")
+            );
+    }
+
+    @Test
+    void missingFieldStrategySkip() {
+        crb.missingFieldStrategy(FieldMismatchStrategy.SKIP);
+        assertThat(readAll("foo,bar\nbaz\nfoo,bar"))
+            .satisfiesExactly(
+                item1 -> CsvRecordAssert.assertThat(item1)
+                    .fields().containsExactly("foo", "bar"),
+                item2 -> CsvRecordAssert.assertThat(item2)
+                    .fields().containsExactly("foo", "bar")
+            );
+    }
+
+    // combined strategies
+
+    @Test
+    void skipExtraIgnoreMissing() {
+        crb.extraFieldStrategy(FieldMismatchStrategy.SKIP)
+            .missingFieldStrategy(FieldMismatchStrategy.IGNORE);
+        assertThat(readAll("a,b\nc\nd,e,f\ng,h"))
+            .satisfiesExactly(
+                item1 -> CsvRecordAssert.assertThat(item1)
+                    .fields().containsExactly("a", "b"),
+                item2 -> CsvRecordAssert.assertThat(item2)
+                    .fields().containsExactly("c"),
+                item3 -> CsvRecordAssert.assertThat(item3)
+                    .fields().containsExactly("g", "h")
+            );
     }
 
     // allow extra characters after closing quotes

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

@@ -19,6 +19,7 @@
 import de.siegmar.fastcsv.reader.CsvReader;
 import de.siegmar.fastcsv.reader.CsvRecord;
 import de.siegmar.fastcsv.reader.CsvRecordHandler;
+import de.siegmar.fastcsv.reader.FieldMismatchStrategy;
 import de.siegmar.fastcsv.reader.FieldModifiers;
 import de.siegmar.fastcsv.reader.NamedCsvRecord;
 import testutil.CsvRecordAssert;
@@ -55,15 +56,15 @@ void multipleRecordsNoSkipEmpty() {
     @ParameterizedTest
     @ValueSource(strings = {",\nfoo\n", ",,\nfoo\n", "''\nfoo\n", "' '\nfoo\n"})
     void notEmpty(final String input) {
-        crb.allowMissingFields(true).quoteCharacter('\'');
+        crb.missingFieldStrategy(FieldMismatchStrategy.IGNORE).quoteCharacter('\'');
         final CsvRecordHandler cbh = CsvRecordHandler.of(c -> c.fieldModifier(FieldModifiers.TRIM));
         assertThat(crb.build(cbh, input).stream()).hasSize(2);
     }
 
     @ParameterizedTest
     @ValueSource(strings = {",\nfoo\n", ",,\nfoo\n", "''\nfoo\n", "' '\nfoo\n"})
     void notEmptyCustomCallback(final String input) {
-        crb.allowMissingFields(true).quoteCharacter('\'');
+        crb.missingFieldStrategy(FieldMismatchStrategy.IGNORE).quoteCharacter('\'');
         final AbstractBaseCsvCallbackHandler<String[]> cbh = new AbstractBaseCsvCallbackHandler<>() {
             private final List<String> fields = new ArrayList<>();
 

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

@@ -19,6 +19,7 @@
 import de.siegmar.fastcsv.reader.CommentStrategy;
 import de.siegmar.fastcsv.reader.CsvReader;
 import de.siegmar.fastcsv.reader.CsvRecord;
+import de.siegmar.fastcsv.reader.FieldMismatchStrategy;
 import testutil.CsvRecordAssert;
 
 @SuppressWarnings("PMD.CloseResource")
@@ -79,7 +80,7 @@ void builderToString() {
             .isEqualTo("""
                 CsvReaderBuilder[fieldSeparator=,, quoteCharacter=", \
                 commentStrategy=NONE, commentCharacter=#, skipEmptyLines=true, \
-                allowExtraFields=false, allowMissingFields=false, allowExtraCharsAfterClosingQuote=false, \
+                extraFieldStrategy=STRICT, missingFieldStrategy=STRICT, allowExtraCharsAfterClosingQuote=false, \
                 trimWhitespacesAroundQuotes=false, detectBomHeader=false, maxBufferSize=16777216]""");
     }
 
@@ -128,12 +129,28 @@ void chained() {
             .commentStrategy(CommentStrategy.NONE)
             .commentCharacter('#')
             .skipEmptyLines(true)
-            .allowExtraFields(false)
-            .allowMissingFields(false)
+            .extraFieldStrategy(FieldMismatchStrategy.STRICT)
+            .missingFieldStrategy(FieldMismatchStrategy.STRICT)
             .allowExtraCharsAfterClosingQuote(false)
             .ofCsvRecord("foo");
 
         assertThat(reader).isNotNull();
     }
 
+    @SuppressWarnings("removal")
+    @Test
+    void deprecatedAllowExtraFields() {
+        assertThat(CsvReader.builder().allowExtraFields(true)
+            .ofCsvRecord("foo\nfoo,bar").stream())
+            .hasSize(2);
+    }
+
+    @SuppressWarnings("removal")
+    @Test
+    void deprecatedAllowMissingFields() {
+        assertThat(CsvReader.builder().allowMissingFields(true)
+            .ofCsvRecord("foo,bar\nfoo").stream())
+            .hasSize(2);
+    }
+
 }

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

@@ -34,7 +34,7 @@ void readerToString() {
         assertThat(crb.ofCsvRecord(""))
             .asString()
             .isEqualTo("CsvReader[commentStrategy=NONE, skipEmptyLines=true, "
-                + "allowExtraFields=false, allowMissingFields=false, parser=RelaxedCsvParser]");
+                + "extraFieldStrategy=STRICT, missingFieldStrategy=STRICT, parser=RelaxedCsvParser]");
     }
 
 }

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

@@ -15,6 +15,7 @@
 import de.siegmar.fastcsv.reader.CommentStrategy;
 import de.siegmar.fastcsv.reader.CsvReader;
 import de.siegmar.fastcsv.reader.CsvRecord;
+import de.siegmar.fastcsv.reader.FieldMismatchStrategy;
 import specreader.CheckVariant;
 import specreader.CheckVariantWrapper;
 import specreader.TestSpecRepository;
@@ -98,8 +99,8 @@ private static List<List<String>> parseCsvRecords(final TestSpecSettings setting
 
         return CsvReader.builder()
             .commentStrategy(commentStrategy)
-            .allowExtraFields(true)
-            .allowMissingFields(true)
+            .extraFieldStrategy(FieldMismatchStrategy.IGNORE)
+            .missingFieldStrategy(FieldMismatchStrategy.IGNORE)
             .skipEmptyLines(settings.skipEmptyLines())
             .ofCsvRecord(input)
             .stream()