1 // Copyright 2009 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package heap provides heap operations for any type that implements 6 // heap.Interface. A heap is a tree with the property that each node is the 7 // minimum-valued node in its subtree. 8 // 9 // The minimum element in the tree is the root, at index 0. 10 // 11 // A heap is a common way to implement a priority queue. To build a priority 12 // queue, implement the Heap interface with the (negative) priority as the 13 // ordering for the Less method, so Push adds items while Pop removes the 14 // highest-priority item from the queue. The Examples include such an 15 // implementation; the file example_pq_test.go has the complete source. 16 // 17 package heap 18 19 import "sort" 20 21 // Any type that implements heap.Interface may be used as a 22 // min-heap with the following invariants (established after 23 // Init has been called or if the data is empty or sorted): 24 // 25 // !h.Less(j, i) for 0 <= i < h.Len() and 2*i+1 <= j <= 2*i+2 and j < h.Len() 26 // 27 // Note that Push and Pop in this interface are for package heap's 28 // implementation to call. To add and remove things from the heap, 29 // use heap.Push and heap.Pop. 30 type Interface interface { 31 sort.Interface 32 Push(x interface{}) // add x as element Len() 33 Pop() interface{} // remove and return element Len() - 1. 34 } 35 36 // A heap must be initialized before any of the heap operations 37 // can be used. Init is idempotent with respect to the heap invariants 38 // and may be called whenever the heap invariants may have been invalidated. 39 // Its complexity is O(n) where n = h.Len(). 40 // 41 func Init(h Interface) { 42 // heapify 43 n := h.Len() 44 for i := n/2 - 1; i >= 0; i-- { 45 down(h, i, n) 46 } 47 } 48 49 // Push pushes the element x onto the heap. The complexity is 50 // O(log(n)) where n = h.Len(). 51 // 52 func Push(h Interface, x interface{}) { 53 h.Push(x) 54 up(h, h.Len()-1) 55 } 56 57 // Pop removes the minimum element (according to Less) from the heap 58 // and returns it. The complexity is O(log(n)) where n = h.Len(). 59 // It is equivalent to Remove(h, 0). 60 // 61 func Pop(h Interface) interface{} { 62 n := h.Len() - 1 63 h.Swap(0, n) 64 down(h, 0, n) 65 return h.Pop() 66 } 67 68 // Remove removes the element at index i from the heap. 69 // The complexity is O(log(n)) where n = h.Len(). 70 // 71 func Remove(h Interface, i int) interface{} { 72 n := h.Len() - 1 73 if n != i { 74 h.Swap(i, n) 75 if !down(h, i, n) { 76 up(h, i) 77 } 78 } 79 return h.Pop() 80 } 81 82 // Fix re-establishes the heap ordering after the element at index i has changed its value. 83 // Changing the value of the element at index i and then calling Fix is equivalent to, 84 // but less expensive than, calling Remove(h, i) followed by a Push of the new value. 85 // The complexity is O(log(n)) where n = h.Len(). 86 func Fix(h Interface, i int) { 87 if !down(h, i, h.Len()) { 88 up(h, i) 89 } 90 } 91 92 func up(h Interface, j int) { 93 for { 94 i := (j - 1) / 2 // parent 95 if i == j || !h.Less(j, i) { 96 break 97 } 98 h.Swap(i, j) 99 j = i 100 } 101 } 102 103 func down(h Interface, i0, n int) bool { 104 i := i0 105 for { 106 j1 := 2*i + 1 107 if j1 >= n || j1 < 0 { // j1 < 0 after int overflow 108 break 109 } 110 j := j1 // left child 111 if j2 := j1 + 1; j2 < n && h.Less(j2, j1) { 112 j = j2 // = 2*i + 2 // right child 113 } 114 if !h.Less(j, i) { 115 break 116 } 117 h.Swap(i, j) 118 i = j 119 } 120 return i > i0 121 } 122
