Add Stack.TryPeek (#315)

Author: SimonCropp

apiCount.include.md

@@ -1 +1 @@
-**API count: 525**
+**API count: 526**

api_list.include.md

@@ -339,6 +339,11 @@
  * `bool Contains<T>(Span<T>, T) where T : IEquatable<T>` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.memoryextensions.contains#system-memoryextensions-contains-1(system-span((-0))-0))
 
 
+#### Stack<T>
+
+ * `bool TryPeek<T>(Stack<T>, T)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.stack-1.trypeek)
+
+
 #### Stream
 
  * `Task CopyToAsync(Stream, Stream, CancellationToken)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.io.stream.copytoasync#system-io-stream-copytoasync(system-io-stream-system-threading-cancellationtoken))

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: 525**<!-- singleLineInclude: apiCount. path: /apiCount.include.md -->
+**API count: 526**<!-- singleLineInclude: apiCount. path: /apiCount.include.md -->
 
 
 **See [Milestones](../../milestones?state=closed) for release notes.**
@@ -813,6 +813,11 @@ The class `Polyfill` includes the following extension methods:
  * `bool Contains<T>(Span<T>, T) where T : IEquatable<T>` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.memoryextensions.contains#system-memoryextensions-contains-1(system-span((-0))-0))
 
 
+#### Stack<T>
+
+ * `bool TryPeek<T>(Stack<T>, T)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.stack-1.trypeek)
+
+
 #### Stream
 
  * `Task CopyToAsync(Stream, Stream, CancellationToken)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.io.stream.copytoasync#system-io-stream-copytoasync(system-io-stream-system-threading-cancellationtoken))

src/Consume/Consume.cs

@@ -548,6 +548,12 @@ void Span_Methods()
 
 #endif
 
+    void Stack_Methods()
+    {
+        var stack = new Stack<char>();
+        stack.TryPeek(out var ch);
+    }
+
     async Task Stream_Methods()
     {
         var input = new byte[] { 1, 2 };

src/Polyfill/Polyfill_Stack.cs

@@ -0,0 +1,31 @@
+// <auto-generated />
+
+#pragma warning disable
+
+namespace Polyfills;
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+
+static partial class Polyfill
+{
+#if NETSTANDARD2_0 || NETFRAMEWORK
+
+    /// <summary>
+    /// Returns a value that indicates whether there is an object at the top of the <see cref="Stack{T}"/>, and if one is present, copies it to the result parameter. The object is not removed from the <see cref="Stack{T}"/>.
+    /// </summary>
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.stack-1.trypeek
+    public static bool TryPeek<T>(this Stack<T> target, [MaybeNullWhen(false)] out T result)
+    {
+        if (target.Count > 0)
+        {
+            result = target.Peek();
+            return true;
+        }
+
+        result = default;
+        return false;
+    }
+
+#endif
+}

src/Tests/PolyfillTests_Stack.cs

@@ -0,0 +1,26 @@
+partial class PolyfillTests
+{
+    [Test]
+    public void Stack_TryPeek()
+    {
+        var stack = new Stack<int>();
+
+        // Test when stack is empty
+        var result = stack.TryPeek(out var value);
+        Assert.IsFalse(result);
+        Assert.AreEqual(0, value);
+
+        // Test when stack has elements
+        stack.Push(1);
+        stack.Push(2);
+        stack.Push(3);
+
+        result = stack.TryPeek(out value);
+        Assert.IsTrue(result);
+        // The top element should be 3
+        Assert.AreEqual(3, value);
+
+        // Ensure the stack is not modified
+        Assert.AreEqual(3, stack.Count);
+    }
+}