docs(website): add example for interpreting empty fields as null values

Author: osiegmar

docs/src/content/docs/guides/Examples/reading-null.mdx

@@ -0,0 +1,22 @@
+---
+title: Reading null values
+---
+
+import SourceExample from '../../../../components/SourceExample.astro';
+
+The concept of **null values** is not part of the CSV standard (per [RFC 4180](https://datatracker.ietf.org/doc/html/rfc4180)).
+
+In some situations, however, it is necessary to interpret certain fields as null values and differentiate them from empty fields.
+One common example is database imports and exports, where the differentiation between null and empty fields is often required.
+
+A core principle of FastCSV is to provide a null-free API, meaning that no public function ever returns null.
+This design choice helps prevent `NullPointerException` and makes user code more robust.
+
+This feature comes with a trade-off: if you absolutely need null values, you will have to implement a workaround.
+
+## Example
+
+The following example demonstrates how to interpret unquoted empty fields as null values by using a custom `FieldModifier`
+that carries the information of `null` in a special marker String value.
+
+<SourceExample filename="ExampleNamedCsvReaderWithNullFields.java"/>

example/src/main/java/example/ExampleNamedCsvReaderWithNullFields.java

@@ -0,0 +1,64 @@
+package example;
+
+import java.util.UUID;
+
+import de.siegmar.fastcsv.reader.CsvReader;
+import de.siegmar.fastcsv.reader.FieldModifier;
+import de.siegmar.fastcsv.reader.NamedCsvRecord;
+import de.siegmar.fastcsv.reader.NamedCsvRecordHandler;
+
+/// Example of interpreting empty, unquoted fields in a CSV as `null` values.
+public class ExampleNamedCsvReaderWithNullFields {
+
+    private static final String DATA = """
+        firstName,middleName,lastName
+        John,,Doe
+        Jane,"",Smith
+        """;
+
+    public static void main(final String[] args) {
+        final NamedCsvRecordHandler callbackHandler = NamedCsvRecordHandler
+            .of(builder -> builder.fieldModifier(new NullFieldModifier()));
+
+        CsvReader.builder().build(callbackHandler, DATA).stream()
+            .map(ExampleNamedCsvReaderWithNullFields::mapPerson)
+            .forEach(System.out::println);
+    }
+
+    static Person mapPerson(final NamedCsvRecord record) {
+        return new Person(
+            nullable(record.getField("firstName")),
+            nullable(record.getField("middleName")),
+            nullable(record.getField("lastName"))
+        );
+    }
+
+    static String nullable(final String fieldValue) {
+        return NullFieldModifier.isNull(fieldValue) ? null : fieldValue;
+    }
+
+    static class NullFieldModifier implements FieldModifier {
+
+        /// A marker to represent null values in the CSV. The unique UUID
+        /// ensures that it does not conflict with any actual data in the CSV.
+        private static final String NULL_MARKER = "NULL:" + UUID.randomUUID();
+
+        /// {@return `NULL_MARKER` for unquoted empty fields,
+        /// otherwise the field value itself}
+        @Override
+        public String modify(final long startingLineNumber, final int fieldIdx,
+                             final boolean quoted, final String field) {
+            return !quoted && field.isEmpty() ? NULL_MARKER : field;
+        }
+
+        /// {@return `true` if the field is the `NULL_MARKER`, otherwise `false`}
+        static boolean isNull(final String field) {
+            return NULL_MARKER.equals(field);
+        }
+
+    }
+
+    record Person(String firstName, String middleName, String lastName) {
+    }
+
+}