From 7614573a181d211374eed4216d602b77645112fe Mon Sep 17 00:00:00 2001
From: maliming <malimings@gmail.com>
Date: Wed, 16 Aug 2023 14:21:10 +0800
Subject: [PATCH] Add `Collection Mapping` document.

---
 docs/en/Object-To-Object-Mapping.md | 48 +++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/docs/en/Object-To-Object-Mapping.md b/docs/en/Object-To-Object-Mapping.md
index c12b260921..f184468bbc 100644
--- a/docs/en/Object-To-Object-Mapping.md
+++ b/docs/en/Object-To-Object-Mapping.md
@@ -326,3 +326,51 @@ A single class may implement more than one `IObjectMapper<TSource, TDestination>
 
 > This approach is powerful since `MyCustomUserMapper` can inject any other service and use in the `Map` methods.
 
+#### Collection Mapping
+
+You only requires configuration of element types, not of any array or list type that might be used. 
+
+For example, we might have a simple source and destination type:
+
+````csharp
+public class Source
+{
+	public int Value { get; set; }
+}
+
+public class Destination
+{
+	public int Value { get; set; }
+}
+````
+
+All the basic generic collection types are supported:
+
+````csharp
+IObjectMapper _objectMapper //inject it.
+
+var sources = new[]
+{
+    new Source { Value = 5 },
+    new Source { Value = 6 },
+    new Source { Value = 7 }
+};
+
+IEnumerable<Destination> ienumerableDest = _objectMapper.Map<Source[], IEnumerable<Destination>>(sources);
+ICollection<Destination> icollectionDest = _objectMapper.Map<Source[], ICollection<Destination>>(sources);
+ICollection<Destination> collectionDest = _objectMapper.Map<Source[], Collection<Destination>>(sources);
+IList<Destination> ilistDest = _objectMapper.Map<Source[], IList<Destination>>(sources);
+List<Destination> listDest = _objectMapper.Map<Source[], List<Destination>>(sources);
+Destination[] arrayDest = _objectMapper.Map<Source[], Destination[]>(sources);
+````
+
+To be specific, the source collection types supported include:
+
+* `IEnumerable<T>`
+* `ICollection<T>`
+* `Collection<T>`
+* `IList<T>`
+* `List<T>`
+* `T[]`
+
+> When mapping to an existing collection, the destination collection is cleared first.