Add PriorityQueue to System.Collections.Generic (dotnet#43957)

This commit adds a new data structure, priority queue.

Fixes dotnet#43957

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

@@ -378,6 +378,50 @@ public void Dispose() { }
             void System.Collections.IEnumerator.Reset() { }
         }
     }
+
+    public partial class PriorityQueue<TElement, TPriority>
+    {
+        public PriorityQueue() { }
+        public PriorityQueue(int initialCapacity) { }
+        public PriorityQueue(System.Collections.Generic.IComparer<TPriority>? comparer) { }
+        public PriorityQueue(int initialCapacity, System.Collections.Generic.IComparer<TPriority>? comparer) { }
+        public PriorityQueue(System.Collections.Generic.IEnumerable<(TElement Element, TPriority Priority)> values) { }
+        public PriorityQueue(System.Collections.Generic.IEnumerable<(TElement Element, TPriority Priority)> values, System.Collections.Generic.IComparer<TPriority>? comparer) { }
+        public int Count { get { throw null; } }
+        public System.Collections.Generic.IComparer<TPriority> Comparer { get { throw null; } }
+        public void Enqueue(TElement element, TPriority priority) { }
+        public TElement Peek() { throw null; }
+        public TElement Dequeue() { throw null; }
+        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; }
+        public TElement EnqueueDequeue(TElement element, TPriority priority) { throw null; }
+        public void EnqueueRange(System.Collections.Generic.IEnumerable<(TElement Element, TPriority Priority)> values) { }
+        public void EnqueueRange(System.Collections.Generic.IEnumerable<TElement> values, TPriority priority) { }
+        public void Clear() { }
+        public void EnsureCapacity(int capacity) { }
+        public void TrimExcess() { }
+        public System.Collections.Generic.PriorityQueue<TElement, TPriority>.UnorderedItemsCollection UnorderedItems { get; }
+        public partial class UnorderedItemsCollection : System.Collections.Generic.IReadOnlyCollection<(TElement Element, TPriority Priority)>, System.Collections.ICollection
+        {
+            public int Count { get { throw null; } }
+            bool System.Collections.ICollection.IsSynchronized { get { throw null; } }
+            object System.Collections.ICollection.SyncRoot { get { throw null; } }
+            public void CopyTo(Array array, int index) { }
+            public partial struct Enumerator : IEnumerator<(TElement TElement, TPriority Priority)>, IEnumerator
+            {
+                (TElement TElement, TPriority Priority) IEnumerator<(TElement TElement, TPriority Priority)>.Current { get { throw null; } }
+                object IEnumerator.Current { get { throw null; } }
+
+                void IDisposable.Dispose() { }
+                bool IEnumerator.MoveNext() { throw null; }
+                void IEnumerator.Reset() { }
+            }
+            public System.Collections.Generic.PriorityQueue<TElement, TPriority>.UnorderedItemsCollection.Enumerator GetEnumerator() { throw null; }
+            System.Collections.Generic.IEnumerator<(TElement Element, TPriority Priority)> System.Collections.Generic.IEnumerable<(TElement Element, TPriority Priority)>.GetEnumerator() { throw null; }
+            System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() { throw null; }
+        }
+    }
+
     public partial class Queue<T> : System.Collections.Generic.IEnumerable<T>, System.Collections.Generic.IReadOnlyCollection<T>, System.Collections.ICollection, System.Collections.IEnumerable
     {
         public Queue() { }

src/libraries/System.Collections/src/System.Collections.csproj

@@ -13,6 +13,7 @@
     <Compile Include="$(CoreLibSharedDir)System\Collections\Generic\IDictionaryDebugView.cs"
              Link="Common\System\Collections\Generic\IDictionaryDebugView.cs" />
     <Compile Include="System\Collections\Generic\LinkedList.cs" />
+    <Compile Include="System\Collections\Generic\PriorityQueue.cs" />
     <Compile Include="System\Collections\Generic\Queue.cs" />
     <Compile Include="System\Collections\Generic\QueueDebugView.cs" />
     <Compile Include="System\Collections\Generic\SortedDictionary.cs" />

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

@@ -0,0 +1,177 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace System.Collections.Generic
+{
+    [System.Runtime.CompilerServices.TypeForwardedFrom("System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089")]
+    public class PriorityQueue<TElement, TPriority>
+    {
+        /// <summary>
+        /// Creates an empty PriorityQueue instance.
+        /// </summary>
+        public PriorityQueue()
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///   Creates a PriorityQueue instance with specified initial capacity in its backing array.
+        /// </summary>
+        public PriorityQueue(int initialCapacity)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///   Creates a PriorityQueue instance with specified priority comparer.
+        /// </summary>
+        public PriorityQueue(IComparer<TPriority>? comparer)
+        {
+            throw new NotImplementedException();
+        }
+
+        public PriorityQueue(int initialCapacity, IComparer<TPriority>? comparer)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///   Creates a PriorityQueue populated with the specified values and priorities.
+        /// </summary>
+        public PriorityQueue(IEnumerable<(TElement Element, TPriority Priority)> values)
+        {
+            throw new NotImplementedException();
+        }
+
+        public PriorityQueue(IEnumerable<(TElement Element, TPriority Priority)> values, IComparer<TPriority>? comparer)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///   Gets the current element count in the queue.
+        /// </summary>
+        public int Count => throw new NotImplementedException();
+
+        /// <summary>
+        ///   Gets the priority comparer of the queue.
+        /// </summary>
+        public IComparer<TPriority> Comparer => throw new NotImplementedException();
+
+        /// <summary>
+        ///   Enqueues the element with specified priority.
+        /// </summary>
+        public void Enqueue(TElement element, TPriority priority)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///   Gets the element with minimal priority, if it exists.
+        /// </summary>
+        /// <exception cref="InvalidOperationException">The queue is empty.</exception>
+        public TElement Peek()
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///    Dequeues the element with minimal priority, if it exists.
+        /// </summary>
+        /// <exception cref="InvalidOperationException">The queue is empty.</exception>
+        public TElement Dequeue()
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///    Try-variants of Dequeue and Peek methods.
+        /// </summary>
+        public bool TryDequeue([MaybeNullWhen(false)] out TElement element, [MaybeNullWhen(false)] out TPriority priority)
+        {
+            throw new NotImplementedException();
+        }
+        public bool TryPeek([MaybeNullWhen(false)] out TElement element, [MaybeNullWhen(false)] out TPriority priority)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///   Combined enqueue/dequeue operation, generally more efficient than sequential Enqueue/Dequeue calls.
+        /// </summary>
+        public TElement EnqueueDequeue(TElement element, TPriority priority)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///   Enqueues a sequence of element/priority pairs to the queue.
+        /// </summary>
+        public void EnqueueRange(IEnumerable<(TElement Element, TPriority Priority)> values)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///   Enqueues a sequence of elements with provided priority.
+        /// </summary>
+        public void EnqueueRange(IEnumerable<TElement> values, TPriority priority)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///   Removes all objects from the PriorityQueue.
+        /// </summary>
+        public void Clear()
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///   Ensures that the PriorityQueue can hold the specified capacity and resizes its underlying buffer if necessary.
+        /// </summary>
+        public void EnsureCapacity(int capacity)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///   Sets capacity to the actual number of elements in the queue, if that is less than 90 percent of current capacity.
+        /// </summary>
+        public void TrimExcess()
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        ///   Gets a collection that enumerates the elements of the queue.
+        /// </summary>
+        public UnorderedItemsCollection UnorderedItems { get; }
+
+        public class UnorderedItemsCollection : IReadOnlyCollection<(TElement Element, TPriority Priority)>, ICollection
+        {
+            public int Count => throw new NotImplementedException();
+            object ICollection.SyncRoot => throw new NotImplementedException();
+            bool ICollection.IsSynchronized => throw new NotImplementedException();
+
+            public void CopyTo(Array array, int index) => throw new NotImplementedException();
+
+            public struct Enumerator : IEnumerator<(TElement TElement, TPriority Priority)>, IEnumerator
+            {
+                (TElement TElement, TPriority Priority) IEnumerator<(TElement TElement, TPriority Priority)>.Current => throw new NotImplementedException();
+                object IEnumerator.Current => throw new NotImplementedException();
+
+                void IDisposable.Dispose() => throw new NotImplementedException();
+                bool IEnumerator.MoveNext() => throw new NotImplementedException();
+                void IEnumerator.Reset() => throw new NotImplementedException();
+            }
+
+            public Enumerator GetEnumerator() => throw new NotImplementedException();
+            IEnumerator<(TElement Element, TPriority Priority)> IEnumerable<(TElement Element, TPriority Priority)>.GetEnumerator() => throw new NotImplementedException();
+            IEnumerator IEnumerable.GetEnumerator() => throw new NotImplementedException();
+        }
+    }
+}

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

@@ -0,0 +1,17 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+using Xunit;
+
+namespace System.Collections.Tests
+{
+    public abstract class PriorityQueue_Generic_Tests<TElement, TPriority> : TestBase<(TElement, TPriority)>
+    {
+        [Fact]
+        public void ConstructorThrows()
+        {
+            Assert.Throws<NotImplementedException>(() => new PriorityQueue<TElement, TPriority>());
+        }
+    }
+}

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

@@ -0,0 +1,21 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace System.Collections.Tests
+{
+    public class PriorityQueue_Generic_Tests_string_string : PriorityQueue_Generic_Tests<string, string>
+    {
+        protected override (string, string) CreateT(int seed)
+        {
+            throw new NotImplementedException();
+        }
+    }
+
+    public class PriorityQueue_Generic_Tests_int_int : PriorityQueue_Generic_Tests<int, int>
+    {
+        protected override (int, int) CreateT(int seed)
+        {
+            throw new NotImplementedException();
+        }
+    }
+}

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

@@ -0,0 +1,17 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+using Xunit;
+
+namespace System.Collections.Tests
+{
+    public class PriorityQueue_NonGeneric_Tests : TestBase
+    {
+        [Fact]
+        public void ConstructorThrows()
+        {
+            Assert.Throws<NotImplementedException>(() => new PriorityQueue<string, string>());
+        }
+    }
+}

src/libraries/System.Collections/tests/System.Collections.Tests.csproj

@@ -95,6 +95,9 @@
     <Compile Include="Generic\List\List.Generic.Tests.Find.cs" />
     <Compile Include="Generic\List\List.Generic.Tests.Remove.cs" />
     <Compile Include="Generic\List\List.Generic.Tests.Sort.cs" />
+    <Compile Include="Generic\PriorityQueue\PriorityQueue.Generic.cs" />
+    <Compile Include="Generic\PriorityQueue\PriorityQueue.Generic.Tests.cs" />
+    <Compile Include="Generic\PriorityQueue\PriorityQueue.Tests.cs" />
     <Compile Include="Generic\Queue\Queue.Generic.cs" />
     <Compile Include="Generic\Queue\Queue.Generic.Tests.cs" />
     <Compile Include="Generic\Queue\Queue.Tests.cs" />