libgo/go/container/heap/heap.go

   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 // The Interface type describes the requirements
  22 // for a type using the routines in this package.
  23 // Any type that implements it may be used as a
  24 // min-heap with the following invariants (established after
  25 // Init has been called or if the data is empty or sorted):
  26 //
  27 //      !h.Less(j, i) for 0 <= i < h.Len() and 2*i+1 <= j <= 2*i+2 and j < h.Len()
  28 //
  29 // Note that Push and Pop in this interface are for package heap's
  30 // implementation to call. To add and remove things from the heap,
  31 // use heap.Push and heap.Pop.
  32 type Interface interface {
  33         sort.Interface
  34         Push(x interface{}) // add x as element Len()
  35         Pop() interface{}   // remove and return element Len() - 1.
  36 }
  37
  38 // Init establishes the heap invariants required by the other routines in this package.
  39 // Init is idempotent with respect to the heap invariants
  40 // and may be called whenever the heap invariants may have been invalidated.
  41 // Its complexity is O(n) where n = h.Len().
  42 func Init(h Interface) {
  43         // heapify
  44         n := h.Len()
  45         for i := n/2 - 1; i >= 0; i-- {
  46                 down(h, i, n)
  47         }
  48 }
  49
  50 // Push pushes the element x onto the heap. The complexity is
  51 // O(log(n)) where n = h.Len().
  52 //
  53 func Push(h Interface, x interface{}) {
  54         h.Push(x)
  55         up(h, h.Len()-1)
  56 }
  57
  58 // Pop removes the minimum element (according to Less) from the heap
  59 // and returns it. The complexity is O(log(n)) where n = h.Len().
  60 // It is equivalent to Remove(h, 0).
  61 //
  62 func Pop(h Interface) interface{} {
  63         n := h.Len() - 1
  64         h.Swap(0, n)
  65         down(h, 0, n)
  66         return h.Pop()
  67 }
  68
  69 // Remove removes the element at index i from the heap.
  70 // The complexity is O(log(n)) where n = h.Len().
  71 //
  72 func Remove(h Interface, i int) interface{} {
  73         n := h.Len() - 1
  74         if n != i {
  75                 h.Swap(i, n)
  76                 if !down(h, i, n) {
  77                         up(h, i)
  78                 }
  79         }
  80         return h.Pop()
  81 }
  82
  83 // Fix re-establishes the heap ordering after the element at index i has changed its value.
  84 // Changing the value of the element at index i and then calling Fix is equivalent to,
  85 // but less expensive than, calling Remove(h, i) followed by a Push of the new value.
  86 // The complexity is O(log(n)) where n = h.Len().
  87 func Fix(h Interface, i int) {
  88         if !down(h, i, h.Len()) {
  89                 up(h, i)
  90         }
  91 }
  92
  93 func up(h Interface, j int) {
  94         for {
  95                 i := (j - 1) / 2 // parent
  96                 if i == j || !h.Less(j, i) {
  97                         break
  98                 }
  99                 h.Swap(i, j)
 100                 j = i
 101         }
 102 }
 103
 104 func down(h Interface, i0, n int) bool {
 105         i := i0
 106         for {
 107                 j1 := 2*i + 1
 108                 if j1 >= n || j1 < 0 { // j1 < 0 after int overflow
 109                         break
 110                 }
 111                 j := j1 // left child
 112                 if j2 := j1 + 1; j2 < n && h.Less(j2, j1) {
 113                         j = j2 // = 2*i + 2  // right child
 114                 }
 115                 if !h.Less(j, i) {
 116                         break
 117                 }
 118                 h.Swap(i, j)
 119                 i = j
 120         }
 121         return i > i0
 122 }