add Enum.TryFormat (#320)

Author: SimonCropp

apiCount.include.md

@@ -1 +1 @@
-**API count: 542**
+**API count: 543**

api_list.include.md

@@ -572,6 +572,7 @@
  * `TEnum Parse<TEnum>(ReadOnlySpan<char>) where TEnum : struct, Enum` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.enum.parse#system-enum-parse-1(system-readonlyspan((system-char))))
  * `TEnum Parse<TEnum>(string, bool) where TEnum : struct, Enum` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.enum.parse#system-enum-parse-1(system-string-system-boolean))
  * `TEnum Parse<TEnum>(string) where TEnum : struct, Enum` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.enum.parse#system-enum-parse-1(system-string-system-boolean))
+ * `bool TryFormat<TEnum>(TEnum, Span<char>, int, ReadOnlySpan<char>) where TEnum : struct, Enum` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.enum.tryformat)
  * `bool TryParse<TEnum>(ReadOnlySpan<char>, bool, TEnum) where TEnum : struct, Enum` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.enum.tryparse#system-enum-tryparse-1(system-readonlyspan((system-char))-system-boolean-0@))
  * `bool TryParse<TEnum>(ReadOnlySpan<char>, TEnum) where TEnum : struct, Enum` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.enum.tryparse#system-enum-tryparse-1(system-readonlyspan((system-char))-0@))
 

readme.md

@@ -12,7 +12,7 @@ The package targets `netstandard2.0` and is designed to support the following ru
  * `net5.0`, `net6.0`, `net7.0`, `net8.0`, `net9.0`, `net10.0`
 
 
-**API count: 542**<!-- singleLineInclude: apiCount. path: /apiCount.include.md -->
+**API count: 543**<!-- singleLineInclude: apiCount. path: /apiCount.include.md -->
 
 
 **See [Milestones](../../milestones?state=closed) for release notes.**
@@ -767,9 +767,9 @@ The class `Polyfill` includes the following extension methods:
 
 #### Random
 
- * `void GetItems<T>(Random, ReadOnlySpan<T>, Span<T>)`
- * `T[] GetItems<T>(Random, ReadOnlySpan<T>, int)`
- * `T[] GetItems<T>(Random, T[], int)`
+ * `void GetItems<T>(Random, ReadOnlySpan<T>, Span<T>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.getitems#system-random-getitems-1(system-readonlyspan((-0))-system-span((-0))))
+ * `T[] GetItems<T>(Random, ReadOnlySpan<T>, int)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.getitems#system-random-getitems-1(system-readonlyspan((-0))-system-int32))
+ * `T[] GetItems<T>(Random, T[], int)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.getitems#system-random-getitems-1(-0()-system-int32))
  * `void NextBytes(Random, Span<byte>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.nextbytes#system-random-nextbytes(system-span((system-byte))))
  * `void Shuffle<T>(Random, T[])` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.nextbytes#system-random-nextbytes(system-span((system-byte))))
  * `void Shuffle<T>(Random, Span<T>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.random.nextbytes#system-random-nextbytes(system-span((system-byte))))
@@ -1046,6 +1046,7 @@ The class `Polyfill` includes the following extension methods:
  * `TEnum Parse<TEnum>(ReadOnlySpan<char>) where TEnum : struct, Enum` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.enum.parse#system-enum-parse-1(system-readonlyspan((system-char))))
  * `TEnum Parse<TEnum>(string, bool) where TEnum : struct, Enum` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.enum.parse#system-enum-parse-1(system-string-system-boolean))
  * `TEnum Parse<TEnum>(string) where TEnum : struct, Enum` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.enum.parse#system-enum-parse-1(system-string-system-boolean))
+ * `bool TryFormat<TEnum>(TEnum, Span<char>, int, ReadOnlySpan<char>) where TEnum : struct, Enum` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.enum.tryformat)
  * `bool TryParse<TEnum>(ReadOnlySpan<char>, bool, TEnum) where TEnum : struct, Enum` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.enum.tryparse#system-enum-tryparse-1(system-readonlyspan((system-char))-system-boolean-0@))
  * `bool TryParse<TEnum>(ReadOnlySpan<char>, TEnum) where TEnum : struct, Enum` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.enum.tryparse#system-enum-tryparse-1(system-readonlyspan((system-char))-0@))
 

src/Polyfill/EnumPolyfill.cs

@@ -133,5 +133,37 @@ public static bool TryParse<TEnum>(ReadOnlySpan<char> value, bool ignoreCase, ou
 #else
         Enum.TryParse<TEnum>(value.ToString(), ignoreCase, out result);
 #endif
+
+    /// <summary>
+    /// Tries to format the value of the enumerated type instance into the provided span of characters.
+    /// </summary>
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.enum.tryformat
+    public static bool TryFormat<TEnum>(TEnum value, Span<char> destination, out int charsWritten, ReadOnlySpan<char> format = default)
+        where TEnum : struct, Enum
+    {
+    #if NET8_0_OR_GREATER
+        return Enum.TryFormat<TEnum>(value, destination, out charsWritten, format);
+    #else
+        string result;
+        if (format.Length == 0)
+        {
+            result = value.ToString();
+        }
+        else
+        {
+            result = Enum.Format(typeof(TEnum), value, format.ToString());
+        }
+
+        if (result.Length > destination.Length)
+        {
+            charsWritten = 0;
+            return false;
+        }
+
+        charsWritten = result.Length;
+        result.CopyTo(destination);
+        return true;
+    #endif
+    }
 #endif
 }

src/Tests/PolyfillTests_Enum.cs

@@ -56,5 +56,34 @@ public void TryParse()
         Assert.True(result);
     }
 
+    enum Colors { Red, Green, Blue }
+
+    [Test]
+    public void EnumTryFormat_ValidValue()
+    {
+        Span<char> buffer = stackalloc char[10];
+        var result = EnumPolyfill.TryFormat(Colors.Green, buffer, out var charsWritten);
+        Assert.IsTrue(result);
+        Assert.AreEqual("Green", buffer[..charsWritten].ToString());
+    }
+
+    [Test]
+    public void EnumTryFormat_BufferTooSmall()
+    {
+        Span<char> buffer = stackalloc char[3];
+        var result = EnumPolyfill.TryFormat(Colors.Blue, buffer, out var charsWritten);
+        Assert.IsFalse(result);
+        Assert.AreEqual(0, charsWritten);
+    }
+
+    [Test]
+    public void EnumTryFormat_WithFormatSpecifier()
+    {
+        Span<char> buffer = stackalloc char[10];
+        var result = EnumPolyfill.TryFormat(Colors.Red, buffer, out var charsWritten, "G");
+        Assert.IsTrue(result);
+        Assert.AreEqual("Red", buffer[..charsWritten].ToString());
+    }
+
 #endif
 }