From 7686af1555aab71b8db0caad294c7e170204aba0 Mon Sep 17 00:00:00 2001 From: Karoy Lorentey Date: Mon, 13 Nov 2023 18:33:43 -0800 Subject: [PATCH 1/2] [Heap] Improve type-level doc comment --- Sources/HeapModule/Heap.swift | 46 ++++++++++++++++++++++++++++++----- 1 file changed, 40 insertions(+), 6 deletions(-) diff --git a/Sources/HeapModule/Heap.swift b/Sources/HeapModule/Heap.swift index 4e7e60e9a..147363de6 100644 --- a/Sources/HeapModule/Heap.swift +++ b/Sources/HeapModule/Heap.swift @@ -9,20 +9,54 @@ // //===----------------------------------------------------------------------===// -/// A [Min-Max Heap](https://en.wikipedia.org/wiki/Min-max_heap) data structure. + +/// A container type implementing a double-ended priority queue. +/// `Heap` is a container of `Comparable` elements that provides immediate +/// access to its minimal and maximal members, and supports removing these items +/// or inserting arbitrary new items in (amortized) logarithmic complexity. /// -/// In a min-max heap, each node at an even level in the tree is less than or -/// equal to all its descendants, while each node at an odd level in the tree is -/// greater than or equal to all of its descendants. +/// var queue: Heap = [3, 4, 1, 2] +/// queue.insert(0) +/// print(queue.min()) // 0 +/// print(queue.popMax()) // 4 +/// print(queue.max()) // 3 /// -/// The implementation is based on [Atkinson et al. 1986]: +/// `Heap` implements the min-max heap data structure, based on +/// [Atkinson et al. 1986]. /// /// [Atkinson et al. 1986]: https://doi.org/10.1145/6617.6621 /// -/// M.D. Atkinson, J.-R. Sack, N. Santoro, T. Strothotte. +/// > M.D. Atkinson, J.-R. Sack, N. Santoro, T. Strothotte. /// "Min-Max Heaps and Generalized Priority Queues." /// *Communications of the ACM*, vol. 29, no. 10, Oct. 1986., pp. 996-1000, /// doi:[10.1145/6617.6621](https://doi.org/10.1145/6617.6621) +/// +/// To efficiently implement these operations, a min-max heap arranges its items +/// into a complete binary tree, maintaining a specific invariant across levels, +/// called the "min-max heap property": each node at an even level in the tree +/// must be less than or equal to all its descendants, while each node at an odd +/// level in the tree must be greater than or equal to all of its descendants. +/// To achieve a compact representation, this tree is stored in breadth-first +/// order inside a single contiguous array value. +/// +/// Unlike most container types, `Heap` doesn't provide a direct way to iterate +/// over the elements it contains -- it isn't a `Sequence` (nor a `Collection`). +/// This is because the order of items in a heap is unspecified and unstable: +/// it may vary between heaps that contain the same set of items, and it may +/// sometimes change in between versions of this library. In particular, the +/// items are (almost) never expected to be in sorted order. +/// +/// For cases where you do need to access the contents of a heap directly and +/// you don't care about their (lack of) order, you can still do so invoking the +/// `unordered` view. This read-only view gives you direct access to the +/// underlying array value: +/// +/// for item in queue.unordered { +/// ... +/// } +/// +/// The name `unordered` highlights the lack of ordering guarantees on the +/// contents, and it helps avoid relying on any particular order. @frozen public struct Heap { @usableFromInline From 19ec155f6089f6de453f8835aad46c09f5fd0b4d Mon Sep 17 00:00:00 2001 From: Karoy Lorentey Date: Tue, 14 Nov 2023 11:06:05 -0800 Subject: [PATCH 2/2] Update Sources/HeapModule/Heap.swift Co-authored-by: Stephen Canon --- Sources/HeapModule/Heap.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/HeapModule/Heap.swift b/Sources/HeapModule/Heap.swift index 147363de6..cf83e074c 100644 --- a/Sources/HeapModule/Heap.swift +++ b/Sources/HeapModule/Heap.swift @@ -47,7 +47,7 @@ /// items are (almost) never expected to be in sorted order. /// /// For cases where you do need to access the contents of a heap directly and -/// you don't care about their (lack of) order, you can still do so invoking the +/// you don't care about their (lack of) order, you can do so by invoking the /// `unordered` view. This read-only view gives you direct access to the /// underlying array value: ///