Add Queue.TryPeek, Queue.TryDequeue

apiCount.include.md

@@ -1,17 +1,17 @@
-**API count: 986**
+**API count: 988**
 
 ### Per Target Framework
 
 | Target | APIs |
 | -- | -- |
-| `net461` | 951 |
-| `net462` | 951 |
-| `net47` | 950 |
-| `net471` | 949 |
-| `net472` | 945 |
-| `net48` | 945 |
-| `net481` | 945 |
-| `netstandard2.0` | 947 |
+| `net461` | 953 |
+| `net462` | 953 |
+| `net47` | 952 |
+| `net471` | 951 |
+| `net472` | 947 |
+| `net48` | 947 |
+| `net481` | 947 |
+| `netstandard2.0` | 949 |
 | `netstandard2.1` | 778 |
 | `netcoreapp2.0` | 870 |
 | `netcoreapp2.1` | 789 |

api_list.include.md

@@ -806,6 +806,8 @@
    * Note: No-op on older targets; the BCL grows the backing storage.
  * `void TrimExcess<T>(int)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.queue-1.trimexcess?view=net-11.0#system-collections-generic-queue-1-trimexcess(system-int32))
    * Note: No-op on older targets; the BCL shrinks the backing storage.
+ * `bool TryPeek<T>(T)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.queue-1.trypeek?view=net-11.0)
+ * `bool TryDequeue<T>(T)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.queue-1.trydequeue?view=net-11.0)
 
 
 #### Random

src/Consume/Consume.cs

@@ -1141,6 +1141,8 @@ void List_Methods()
     void Queue_Methods()
     {
         var queue = new Queue<char>();
+        queue.TryPeek(out var ch1);
+        queue.TryDequeue(out var ch2);
         queue.EnsureCapacity(1);
         queue.TrimExcess(1);
         queue.TrimExcess();

src/Polyfill/Polyfill_Queue.cs

@@ -1,6 +1,7 @@
 namespace Polyfills;
 
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 static partial class Polyfill
 {
@@ -28,5 +29,41 @@ public static void TrimExcess<T>(this Queue<T> target, int capacity)
     {
     }
 
+#endif
+
+#if NETSTANDARD2_0 || NETFRAMEWORK
+
+    /// <summary>
+    /// Returns a value that indicates whether there is an object at the beginning of the <see cref="Queue{T}"/>, and if one is present, copies it to the result parameter. The object is not removed from the <see cref="Queue{T}"/>.
+    /// </summary>
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.queue-1.trypeek?view=net-11.0
+    public static bool TryPeek<T>(this Queue<T> target, [MaybeNullWhen(false)] out T result)
+    {
+        if (target.Count > 0)
+        {
+            result = target.Peek();
+            return true;
+        }
+
+        result = default;
+        return false;
+    }
+
+    /// <summary>
+    /// Removes the object at the beginning of the <see cref="Queue{T}"/>, and copies it to the result parameter.
+    /// </summary>
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.queue-1.trydequeue?view=net-11.0
+    public static bool TryDequeue<T>(this Queue<T> target, [MaybeNullWhen(false)] out T result)
+    {
+        if (target.Count > 0)
+        {
+            result = target.Dequeue();
+            return true;
+        }
+
+        result = default;
+        return false;
+    }
+
 #endif
 }

src/Tests/PolyfillTests_Queue.cs

@@ -22,4 +22,53 @@ public async Task Queue_TrimExcess()
         // Should not throw
         await Assert.That(queue.Count).IsEqualTo(10);
     }
+
+    [Test]
+    public async Task Queue_TryPeek()
+    {
+        var queue = new Queue<int>();
+
+        // Test when queue is empty
+        var result = queue.TryPeek(out var value);
+        await Assert.That(result).IsFalse();
+        await Assert.That(value).IsEqualTo(0);
+
+        // Test when queue has elements
+        queue.Enqueue(1);
+        queue.Enqueue(2);
+        queue.Enqueue(3);
+
+        result = queue.TryPeek(out value);
+        await Assert.That(result).IsTrue();
+        // The top element should be 1
+        await Assert.That(value).IsEqualTo(1);
+
+        // Ensure the queue is not modified
+        await Assert.That(queue.Count).IsEqualTo(3);
+    }
+
+    [Test]
+    public async Task Queue_TryDequeue()
+    {
+        var queue = new Queue<int>();
+
+        // Test when queue is empty
+        var result = queue.TryDequeue(out var value);
+        await Assert.That(result).IsFalse();
+        await Assert.That(value).IsEqualTo(0);
+
+        // Test when queue has elements
+        queue.Enqueue(1);
+        queue.Enqueue(2);
+        queue.Enqueue(3);
+
+        result = queue.TryDequeue(out value);
+        await Assert.That(result).IsTrue();
+        // The top element should be 1
+        await Assert.That(value).IsEqualTo(1);
+
+        // Ensure the queue is modified
+        await Assert.That(queue.Count).IsEqualTo(2);
+        await Assert.That(queue.Peek()).IsEqualTo(2);
+    }
 }