Implement PriorityQueue.Remove

src/libraries/System.Collections/ref/System.Collections.cs

@@ -126,6 +126,7 @@ public partial class PriorityQueue<TElement, TPriority>
         public void EnqueueRange(System.Collections.Generic.IEnumerable<TElement> elements, TPriority priority) { }
         public int EnsureCapacity(int capacity) { throw null; }
         public TElement Peek() { throw null; }
+        public bool Remove(TElement element, [System.Diagnostics.CodeAnalysis.MaybeNullWhenAttribute(false)] out TElement removedElement, [System.Diagnostics.CodeAnalysis.MaybeNullWhenAttribute(false)] out TPriority priority, System.Collections.Generic.IEqualityComparer<TElement>? equalityComparer = null) { throw null; }
         public void TrimExcess() { }
         public bool TryDequeue([System.Diagnostics.CodeAnalysis.MaybeNullWhenAttribute(false)] out TElement element, [System.Diagnostics.CodeAnalysis.MaybeNullWhenAttribute(false)] out TPriority priority) { throw null; }
         public bool TryPeek([System.Diagnostics.CodeAnalysis.MaybeNullWhenAttribute(false)] out TElement element, [System.Diagnostics.CodeAnalysis.MaybeNullWhenAttribute(false)] out TPriority priority) { throw null; }

src/libraries/System.Collections/src/System/Collections/Generic/PriorityQueue.cs

@@ -502,6 +502,56 @@ public void EnqueueRange(IEnumerable<TElement> elements, TPriority priority)
             }
         }
 
+        /// <summary>
+        /// Removes the first occurrence the equals the specified parameter.
+        /// </summary>
+        /// <param name="element">The element to look for.</param>
+        /// <param name="removedElement">The actual element that got removed from the queue.</param>
+        /// <param name="priority">The priority value associated with the removed element.</param>
+        /// <param name="equalityComparer">The equality comparer governing element equality.</param>
+        /// <returns><see langword="true"/> if matching entry was found and removed, <see langword="false"/> otherwise.</returns>
+        /// <remarks>
+        /// The method performs a linear-time scan of every element in the heap, removing the first value found to match the <paramref name="element"/> parameter.
+        /// In case of duplicate entries, what entry does get removed is non-deterministic, does not take priority into account and reflects the structure of the heap at the time of removal.
+        /// </remarks>
+        public bool Remove(
+            TElement element,
+            [MaybeNullWhen(false)] out TElement removedElement,
+            [MaybeNullWhen(false)] out TPriority priority,
+            IEqualityComparer<TElement>? equalityComparer = null)
+        {
+            int index = FindIndex(element, equalityComparer);
+            if (index == -1)
+            {
+                removedElement = default;
+                priority = default;
+                return false;
+            }
+
+            (TElement Element, TPriority Priority)[] nodes = _nodes;
+            (removedElement, priority) = nodes[index];
+            int newSize = --_size;
+
+            if (index < newSize)
+            {
+                // We're removing an element from the middle of the heap.
+                // Pop the last element in the collection and sift downward from the removed index.
+                (TElement Element, TPriority Priority) lastNode = nodes[newSize];
+
+                if (_comparer == null)
+                {
+                    MoveDownDefaultComparer(lastNode, index);
+                }
+                else
+                {
+                    MoveDownCustomComparer(lastNode, index);
+                }
+            }
+
+            nodes[newSize] = default;
+            return true;
+        }
+
         /// <summary>
         ///  Removes all items from the <see cref="PriorityQueue{TElement, TPriority}"/>.
         /// </summary>
@@ -809,6 +859,42 @@ private void MoveDownCustomComparer((TElement Element, TPriority Priority) node,
             nodes[nodeIndex] = node;
         }
 
+        /// <summary>
+        /// Scans the heap for the first index containing an element equal to the specified parameter.
+        /// </summary>
+        private int FindIndex(TElement element, IEqualityComparer<TElement>? equalityComparer)
+        {
+            equalityComparer ??= EqualityComparer<TElement>.Default;
+            (TElement Element, TPriority Priority)[] nodes = _nodes;
+            int size = _size;
+
+            // Currently the JIT doesn't optimize direct EqualityComparer<T>.Default.Equals
+            // calls for reference types, so we want to cache the comparer instance instead.
+            // TODO https://github.com/dotnet/runtime/issues/10050: Update if this changes in the future.
+            if (typeof(TElement).IsValueType && equalityComparer == EqualityComparer<TElement>.Default)
+            {
+                for (int i = 0; i < size; i++)
+                {
+                    if (EqualityComparer<TElement>.Default.Equals(element, nodes[i].Element))
+                    {
+                        return i;
+                    }
+                }
+            }
+            else
+            {
+                for (int i = 0; i < size; i++)
+                {
+                    if (equalityComparer.Equals(element, nodes[i].Element))
+                    {
+                        return i;
+                    }
+                }
+            }
+
+            return -1;
+        }
+
         /// <summary>
         /// Initializes the custom comparer to be used internally by the heap.
         /// </summary>

src/libraries/System.Collections/tests/Generic/PriorityQueue/PriorityQueue.Generic.Tests.cs

@@ -93,7 +93,7 @@ public void PriorityQueue_EnumerableConstructor_ShouldContainAllElements(int cou
 
         #endregion
 
-        #region Enqueue, Dequeue, Peek, EnqueueDequeue, DequeueEnqueue
+        #region Enqueue, Dequeue, Peek, EnqueueDequeue, DequeueEnqueue, Remove
 
         [Theory]
         [MemberData(nameof(ValidCollectionSizes))]
@@ -246,6 +246,35 @@ public void PriorityQueue_DequeueEnqueue(int count)
             AssertExtensions.CollectionEqual(expectedItems, queue.UnorderedItems, EqualityComparer<(TElement, TPriority)>.Default);
         }
 
+        [Theory]
+        [MemberData(nameof(ValidCollectionSizes))]
+        public void PriorityQueue_Remove_AllElements(int count)
+        {
+            bool result;
+            TElement removedElement;
+            TPriority removedPriority;
+
+            PriorityQueue<TElement, TPriority> queue = CreatePriorityQueue(count, count, out List<(TElement element, TPriority priority)> generatedItems);
+
+            for (int i = count - 1; i >= 0; i--)
+            {
+                (TElement element, TPriority priority) = generatedItems[i];
+
+                result = queue.Remove(element, out removedElement, out removedPriority);
+
+                Assert.True(result);
+                Assert.Equal(element, removedElement);
+                Assert.Equal(priority, removedPriority);
+                Assert.Equal(i, queue.Count);
+            }
+
+            result = queue.Remove(default, out removedElement, out removedPriority);
+
+            Assert.False(result);
+            Assert.Equal(default, removedElement);
+            Assert.Equal(default, removedPriority);
+        }
+
         #endregion
 
         #region Clear

src/libraries/System.Collections/tests/Generic/PriorityQueue/PriorityQueue.Tests.cs

@@ -167,6 +167,41 @@ public void PriorityQueue_Generic_EnqueueRange_Null()
             Assert.Equal("not null", queue.Dequeue());
         }
 
+        [Fact]
+        public void PriorityQueue_Generic_Remove_MatchingElement()
+        {
+            PriorityQueue<string, int> queue = new PriorityQueue<string, int>();
+            queue.EnqueueRange([("value0", 0), ("value1", 1), ("value2", 2)]);
+
+
+            Assert.True(queue.Remove("value1", out string removedElement, out int removedPriority));
+            Assert.Equal("value1", removedElement);
+            Assert.Equal(1, removedPriority);
+        }
+
+        [Fact]
+        public void PriorityQueue_Generic_Remove_MismatchElement()
+        {
+            PriorityQueue<string, int> queue = new PriorityQueue<string, int>();
+            queue.EnqueueRange([("value0", 0), ("value1", 1), ("value2", 2)]);
+
+            Assert.False(queue.Remove("value4", out string removedElement, out int removedPriority));
+            Assert.Null(removedElement);
+            Assert.Equal(0, removedPriority);
+        }
+
+        [Fact]
+        public void PriorityQueue_Generic_Remove_CustomEqualityComparer()
+        {
+            PriorityQueue<string, int> queue = new PriorityQueue<string, int>();
+            queue.EnqueueRange([("value0", 0), ("value1", 1), ("value2", 2)]);
+            EqualityComparer<string> equalityComparer = EqualityComparer<string>.Create((left, right) => left[^1] == right[^1]);
+
+            Assert.True(queue.Remove("someOtherValue1", out string removedElement, out int removedPriority, equalityComparer));
+            Assert.Equal("value1", removedElement);
+            Assert.Equal(1, removedPriority);
+        }
+
         [Fact]
         public void PriorityQueue_Constructor_int_Negative_ThrowsArgumentOutOfRangeException()
         {
@@ -207,6 +242,16 @@ public void PriorityQueue_EmptyCollection_Peek_ShouldReturnFalse()
             Assert.Throws<InvalidOperationException>(() => queue.Peek());
         }
 
+        [Fact]
+        public void PriorityQueue_EmptyCollection_Remove_ShouldReturnFalse()
+        {
+            var queue = new PriorityQueue<string, string>();
+
+            Assert.False(queue.Remove(element: "element", out string removedElement, out string removedPriority));
+            Assert.Null(removedElement);
+            Assert.Null(removedPriority);
+        }
+
         #region EnsureCapacity, TrimExcess
 
         [Fact]