Add fallback encoding to read all text; Add upgrade guide

Author: Jan5366x

MagicFileEncoding/FileEncoding.cs

@@ -40,10 +40,11 @@ public static string ReadAllText(string filename)
         /// </summary>
         /// <param name="filename">The file to read text</param>
         /// <param name="targetEncoding">The target encoding to transform to the return value</param>
+        /// <param name="fallbackEncoding">Fallback encoding for the input</param>
         /// <returns>Returns the text</returns>
-        public static string ReadAllText(string filename, Encoding targetEncoding)
+        public static string ReadAllText(string filename, Encoding targetEncoding, Encoding fallbackEncoding = null)
             => targetEncoding
-                .GetString(AutomaticTransformBytes(filename, targetEncoding))
+                .GetString(AutomaticTransformBytes(filename, targetEncoding, fallbackEncoding))
                 .Trim(new[]{'\uFEFF'});
 
         /// <summary>
@@ -59,10 +60,12 @@ public static void WriteAllText(string path, string text, Encoding targetEncodin
         /// Automatic transform bytes
         /// </summary>
         /// <param name="filename">The file to analyze</param>
-        /// <param name="targetEncoding"></param>
+        /// <param name="targetEncoding">The output target encoding</param>
+        /// <param name="fallbackEncoding">Fallback encoding for the input</param>
         /// <returns>Transformed byte array</returns>
-        private static byte[] AutomaticTransformBytes(string filename, Encoding targetEncoding) 
-            => Encoding.Convert(GetAcceptableEncoding(filename), targetEncoding,
+        private static byte[] AutomaticTransformBytes(string filename, Encoding targetEncoding, 
+            Encoding fallbackEncoding = null) 
+            => Encoding.Convert(GetAcceptableEncoding(filename,fallbackEncoding), targetEncoding,
                 File.ReadAllBytes(filename));
 
         /// <summary>

README.md

@@ -13,6 +13,8 @@ It is strongly recommended to write unit tests for your use case to ensure the l
 
 #### Read a text file
 ```csharp
+var text = FileEncoding.ReadAllText(filePath);
+// or 
 var text = FileEncoding.ReadAllText(filePath, Encoding.Unicode);
 ```
 #### Write a text file

documentation/upgrade_guide_1_0_0_to_1_1_1.md

@@ -0,0 +1,47 @@
+# Upgrade Guide v1.0.0 to v1.1.1
+
+#### Read a text file
+
+```csharp
+// v1.0.0
+var text = new FileEncoding().AutomaticReadAllText(filename);
+```
+changes to:
+```csharp
+// v1.1.1
+var text = FileEncoding.ReadAllText(filePath);
+// or 
+var text = FileEncoding.ReadAllText(filePath, Encoding.Unicode);
+```
+#### Write a text file
+```csharp
+// v1.0.0
+new FileEncoding().WriteAllText(tmpFile.Path, text, Encoding.UTF8);
+```
+changes to:
+```csharp
+// v1.1.1
+FileEncoding.WriteAllText(tmpFile.Path, text, Encoding.UTF8);
+```
+### Just detect suitable encoding
+```csharp
+// v1.0.0
+var encoding = new FileEncoding().GetAcceptableEncoding(filename);
+```
+changes to:
+```csharp
+// v1.1.1
+var encoding = FileEncoding.GetAcceptableEncoding(filename);
+```
+#### Change fallback (default) encoding
+```csharp
+// v1.0.0
+var fe = new FileEncoding();
+fe.FallbackEncoding = Encoding.UTF8;
+var text = fe.AutomaticReadAllText(filename);
+```
+changes to:
+```csharp
+// v1.1.1
+var text = FileEncoding.ReadAllText(filePath, Encoding.Unicode, Encoding.UTF8);
+```