add ExampleCsvReaderMapping example

docs/src/content/docs/faq.md

@@ -121,36 +121,7 @@ See also: https://github.com/osiegmar/FastCSV/issues/103
 
 #### Does FastCSV support automatic bean mapping?
 
-The goals of FastCSV are not going hand in hand with automatic bean mapping as it would increase the complexity and
-footprint of the library and decrease its performance.
-
-If FastCSV otherwise suits your needs, you can easily map CSV records to beans using the Java stream API. 
-
-```java
-public class Test {
-
-    public static void main(String[] args) throws IOException {
-        var file = Paths.get("input.csv");
-        try (var csv = CsvReader.builder().ofNamedCsvRecord(file)) {
-            csv.stream()
-                .map(Test::mapPerson)
-                .forEach(System.out::println);
-        }
-    }
-
-    private static Person mapPerson(NamedCsvRecord rec) {
-        return new Person(
-            Long.parseLong(rec.getField("ID")),
-            rec.getField("firstName"),
-            rec.getField("lastName")
-        );
-    }
-
-    private record Person(Long id, String firstName, String lastName) {
-    }
-
-}
-```
+See [Bean Mapping example](/guides/examples/bean-mapping/) for more information.
 
 #### Does FastCSV support automatic type conversion?
 

docs/src/content/docs/guides/Examples/bean-mapping.mdx

@@ -0,0 +1,17 @@
+---
+title: Bean Mapping
+---
+
+import SourceExample from '../../../../components/SourceExample.astro';
+
+Many CSV libraries come with built-in support for mapping CSV records to Java beans.
+While this is a convenient feature, the reflection-based approach used by most libraries comes with
+a heavy performance penalty, which contradicts FastCSV’s design goal of being fast.
+
+Thanks to Java stream mapping, FastCSV can provide a similar feature without sacrificing performance.
+
+## Example
+
+The following example demonstrates how to map CSV records to Java beans using FastCSV.
+
+<SourceExample filename="ExampleCsvReaderMapping.java"/>

example/src/main/java/example/ExampleCsvReaderMapping.java

@@ -0,0 +1,43 @@
+package example;
+
+import java.io.IOException;
+import java.util.stream.Stream;
+
+import de.siegmar.fastcsv.reader.CsvReader;
+import de.siegmar.fastcsv.reader.NamedCsvRecord;
+
+/**
+ * Example for reading CSV data with a mapping function.
+ */
+public class ExampleCsvReaderMapping {
+
+    private static final String DATA = """
+        ID,firstName,lastName
+        1,John,Doe
+        2,Jane,Smith
+        """;
+
+    public static void main(final String[] args) throws IOException {
+        try (var persons = readPersons()) {
+            persons.forEach(System.out::println);
+        }
+    }
+
+    private static Stream<Person> readPersons() throws IOException {
+        try (var csv = CsvReader.builder().ofNamedCsvRecord(DATA)) {
+            return csv.stream().map(ExampleCsvReaderMapping::mapPerson);
+        }
+    }
+
+    private static Person mapPerson(final NamedCsvRecord rec) {
+        return new Person(
+            Long.parseLong(rec.getField("ID")),
+            rec.getField("firstName"),
+            rec.getField("lastName")
+        );
+    }
+
+    private record Person(long id, String firstName, String lastName) {
+    }
+
+}