From 1462f6ad5915836315246707521259b62b52b0f6 Mon Sep 17 00:00:00 2001
From: Oliver Siegmar <oliver@siegmar.de>
Date: Sat, 21 Sep 2024 22:05:42 +0200
Subject: [PATCH] add ExampleCsvReaderMapping example

---
 docs/src/content/docs/faq.md                  | 31 +------------
 .../docs/guides/Examples/bean-mapping.mdx     | 17 ++++++++
 .../java/example/ExampleCsvReaderMapping.java | 43 +++++++++++++++++++
 3 files changed, 61 insertions(+), 30 deletions(-)
 create mode 100644 docs/src/content/docs/guides/Examples/bean-mapping.mdx
 create mode 100644 example/src/main/java/example/ExampleCsvReaderMapping.java

diff --git a/docs/src/content/docs/faq.md b/docs/src/content/docs/faq.md
index 47f490b4..0c58fdbe 100644
--- a/docs/src/content/docs/faq.md
+++ b/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?
 
diff --git a/docs/src/content/docs/guides/Examples/bean-mapping.mdx b/docs/src/content/docs/guides/Examples/bean-mapping.mdx
new file mode 100644
index 00000000..8b657625
--- /dev/null
+++ b/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"/>
diff --git a/example/src/main/java/example/ExampleCsvReaderMapping.java b/example/src/main/java/example/ExampleCsvReaderMapping.java
new file mode 100644
index 00000000..5a5feda6
--- /dev/null
+++ b/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) {
+    }
+
+}