chore: Merge pull request #914 from DocSvartz/docs-separate-datatypes

Fix docs: split datatype.md to specific types of topics

Author: DocSvartz

docs/api/Reference.md

@@ -11,7 +11,7 @@ uid: Mapster.References
 | `src.Adapt<Dest>()`     | Mapping to new type | [basic](xref:Mapster.Mapping.BasicUsages) |
 | `src.Adapt(dest)`       | Mapping to existing object      | [basic](xref:Mapster.Mapping.BasicUsages) |
 | `query.ProjectToType<Dest>()` | Mapping from queryable     | [basic](xref:Mapster.Mapping.BasicUsages) |
-| | Convention & Data type support | [data types](xref:Mapster.Mapping.DataTypes) |
+| | Convention & Data type support | [data types](xref:Mapster.Mapping.DataTypes.Overview) |
 
 ### Mapper instance (for dependency injection)
 
@@ -84,7 +84,7 @@ uid: Mapster.References
 | `BeforeMapping` | Add steps before mapping start |  | [before-after](xref:Mapster.Settings.BeforeAfterMapping) |
 | `ConstructUsing` | Define how to create object | x | [constructor](xref:Mapster.Settings.ConstructorMapping) |
 | `EnableNonPublicMembers` | Mapping non-public properties |  | [non-public](xref:Mapster.Settings.Custom.NonPublicMembers) |
-| `EnumMappingStrategy` | Choose whether mapping enum by value or by name |  | [data types](xref:Mapster.Mapping.DataTypes) |
+| `EnumMappingStrategy` | Choose whether mapping enum by value or by name |  | [data types](xref:Mapster.Mapping.DataTypes.Primitives) |
 | `Fork` | Add new settings without side effect on main config | x | [nested mapping](xref:Mapster.Configuration.NestedMapping) |
 | `GetMemberName` | Define how to resolve property name | x | [custom naming](xref:Mapster.Settings.Custom.NamingConvention) |
 | `Ignore` | Ignore specific properties | x | [ignore](xref:Mapster.Settings.Custom.IgnoringMembers) |

docs/articles/mapping/Data-types.md

@@ -0,0 +1,13 @@
+---
+uid: Mapster.Mapping.DataTypes.Collections
+title: "Mapping - Collections"
+---
+
+## Collections
+
+This includes mapping among lists, arrays, collections, dictionary including various interfaces: `IList<T>`, `ICollection<T>`, `IEnumerable<T>`, `ISet<T>`, `IDictionary<TKey, TValue>` etc...
+
+```csharp
+var list = db.Pocos.ToList();
+var target = list.Adapt<IEnumerable<Dto>>();
+```

docs/articles/mapping/data-types/Collections.md

@@ -0,0 +1,50 @@
+---
+uid: Mapster.Mapping.DataTypes.Overview
+title: "Mapping - Mappable Objects"
+---
+
+## Mappable Objects
+
+Mapster can map two different objects using the following rules:
+
+- Source and destination property names are the same. Ex: `dest.Name = src.Name`
+- Source has get method. Ex: `dest.Name = src.GetName()`
+- Source property has child object which can flatten to destination. Ex: `dest.ContactName = src.Contact.Name` or `dest.Contact_Name = src.Contact.Name`
+
+Example:
+
+```csharp
+class Staff {
+    public string Name { get; set; }
+    public int GetAge() {
+        return (DateTime.Now - this.BirthDate).TotalDays / 365.25;
+    }
+    public Staff Supervisor { get; set; }
+    ...
+}
+
+struct StaffDto {
+    public string Name { get; set; }
+    public int Age { get; set; }
+    public string SupervisorName { get; set; }
+}
+
+var dto = staff.Adapt<StaffDto>();
+//dto.Name = staff.Name, dto.Age = staff.GetAge(), dto.SupervisorName = staff.Supervisor.Name
+```
+
+**Mappable Object types are included:**
+
+- POCO classes
+- POCO structs
+- POCO interfaces
+- Dictionary type implement `IDictionary<string, T>`
+- Record types (either class, struct, and interface)
+
+Example for object to dictionary:
+
+```csharp
+var point = new { X = 2, Y = 3 };
+var dict = point.Adapt<Dictionary<string, int>>();
+dict["Y"].ShouldBe(3);
+```

docs/articles/mapping/data-types/Mappable-Objects.md

@@ -0,0 +1,40 @@
+---
+uid: Mapster.Mapping.DataTypes.Primitives
+title: "Mapping - Primitive Types"
+---
+
+## Primitives
+
+Converting between primitive types (ie. int, bool, double, decimal) is supported, including when those types are nullable. For all other types, if you can cast types in c#, you can also cast in Mapster.
+
+```csharp
+decimal i = 123.Adapt<decimal>(); //equal to (decimal)123;
+```
+
+## Enums
+
+Mapster maps enums to numerics automatically, but it also maps strings to and from enums automatically in a fast manner.  
+The default Enum.ToString() in .NET is quite slow. The implementation in Mapster is double the speed. Likewise, a fast conversion from strings to enums is also included.  If the string is null or empty, the enum will initialize to the first enum value.
+
+In Mapster, flagged enums are also supported.
+
+```csharp
+var e = "Read, Write, Delete".Adapt<FileShare>();
+//FileShare.Read | FileShare.Write | FileShare.Delete
+```
+
+For enum to enum with different type, by default, Mapster will map enum by value. You can override to map enum by name by:
+
+```csharp
+TypeAdapterConfig.GlobalSettings.Default
+    .EnumMappingStrategy(EnumMappingStrategy.ByName);
+```
+
+## Strings
+
+When Mapster maps other types to string, Mapster will use `ToString` method. And whenever Mapster maps string to the other types, Mapster will use `Parse` method.
+
+```csharp
+var s = 123.Adapt<string>(); //equal to 123.ToString();
+var i = "123".Adapt<int>();  //equal to int.Parse("123");
+```