Priority queue implementation

[AmanuelEphrem]

Purpose

This PR adds the priority queue data structure into the swift collections, as a response to issue #3. The uses for priority queues are expansive, as they are used in graph searching algorithms, networking algorithms, sorting algorithms, data compression, and much more. Including this data structure in the swift collections would accelerate developer productivity, as they wouldn’t be bogged down by implementation details, and ensure an efficient implementation.

Details

This implementation uses an array-based binary heap as the underlying storage, to take advantage of its O(log(n)) time complexity for enqueue() and dequeue() operations. It enforces that all elements of the PriorityQueue conform to the Comparable protocol so that priority between elements can be determined. While each element could have an associated priority, this implementation would be memory intensive, as @lorentey has previously stated. I believe this drawback is too costly, especially for its initial implementation, and is why I chose against writing it this way (for now at least).

Incomplete Tasks

Currently, I have implemented the PriorityQueue functions, added tests for each of them, and included a markdown page. Tasks that still need to be accomplished include:

• Benchmark testing
• General testing (the tests I have included may not be comprehensive enough)

Future Tasks

• Adding conformity to the CustomStringConvertible protocol
• Adding conformity to the Equitable protocol

Evidently this is a work-in-progress PR and would greatly appreciate both feedback and help in completing the Incomplete Tasks 😃

Checklist

• I've read the Contribution Guidelines
• My contributions are licensed under the Swift license.
• I've followed the coding style of the rest of the project.
• I've added tests covering all new code paths my change adds to the project (if appropriate).
• I've added benchmarks covering new functionality (if appropriate).
• I've verified that my change does not break any existing tests or introduce unexplained benchmark regressions.
• I've updated the documentation if necessary.

[lorentey]

Thanks for implementing this! As discussed in #3, we'd like to implement a min-max heap. Would you be interested in working on that?

This variant could still be useful as a reference implementation to validate we got the expected performance results.

[AmanuelEphrem]

@lorentey, thank you for the fast reply and comments. I seemed to have jumped the gun and went straight into the priority queue, so I can easily convert the PriorityQueue.swift file into a general min/max heap implementation.

It looks like @AquaGeek and I both accidentally implemented (more or less) the same min/max heap, so we can also find ways to consolidate both our implementations into one. I think if we keep my PriorityQueue.swift file (going to change it to Heap.swift) and then keep @AquaGeek 's PriorityQueue.swift as a wrapper over Heap.swift that can work nicely. Currently I am forcing the user to choose between a min or max heap, but @AquaGeek implemented (wonderfully) a min and max heap. So this is a place where we can "merge" @AquaGeek 's additional functions with my Heap.swift file. This way, conformance to the Sequence protocol would not be effected.

Please let me know how this method to consolidate both implementations look, and feel free to suggest a new way of doing it. This is just my initial thoughts, so any and all feedback would be great!

[AquaGeek]

It looks like @AquaGeek and I both accidentally implemented (more or less) the same min/max heap, so we can also find ways to consolidate both our implementations into one.

I'd be happy to work together to consolidate our two implementations!