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 // A heap is a common way to implement a priority queue. To build a priority
  10 // queue, implement the Heap interface with the (negative) priority as the
  11 // ordering for the Less method, so Push adds items while Pop removes the
  12 // highest-priority item from the queue. The Examples include such an
  13 // implementation; the file example_pq_test.go has the complete source.
  14 //
  15 package heap
  16
  17 import "sort"
  18
  19 // Any type that implements heap.Interface may be used as a
  20 // min-heap with the following invariants (established after
  21 // Init has been called or if the data is empty or sorted):
  22 //
  23 //      !h.Less(j, i) for 0 <= i < h.Len() and j = 2*i+1 or 2*i+2 and j < h.Len()
  24 //
  25 // Note that Push and Pop in this interface are for package heap's
  26 // implementation to call.  To add and remove things from the heap,
  27 // use heap.Push and heap.Pop.
  28 type Interface interface {
  29         sort.Interface
  30         Push(x interface{}) // add x as element Len()
  31         Pop() interface{}   // remove and return element Len() - 1.
  32 }
  33
  34 // A heap must be initialized before any of the heap operations
  35 // can be used. Init is idempotent with respect to the heap invariants
  36 // and may be called whenever the heap invariants may have been invalidated.
  37 // Its complexity is O(n) where n = h.Len().
  38 //
  39 func Init(h Interface) {
  40         // heapify
  41         n := h.Len()
  42         for i := n/2 - 1; i >= 0; i-- {
  43                 down(h, i, n)
  44         }
  45 }
  46
  47 // Push pushes the element x onto the heap. The complexity is
  48 // O(log(n)) where n = h.Len().
  49 //
  50 func Push(h Interface, x interface{}) {
  51         h.Push(x)
  52         up(h, h.Len()-1)
  53 }
  54
  55 // Pop removes the minimum element (according to Less) from the heap
  56 // and returns it. The complexity is O(log(n)) where n = h.Len().
  57 // Same as Remove(h, 0).
  58 //
  59 func Pop(h Interface) interface{} {
  60         n := h.Len() - 1
  61         h.Swap(0, n)
  62         down(h, 0, n)
  63         return h.Pop()
  64 }
  65
  66 // Remove removes the element at index i from the heap.
  67 // The complexity is O(log(n)) where n = h.Len().
  68 //
  69 func Remove(h Interface, i int) interface{} {
  70         n := h.Len() - 1
  71         if n != i {
  72                 h.Swap(i, n)
  73                 down(h, i, n)
  74                 up(h, i)
  75         }
  76         return h.Pop()
  77 }
  78
  79 func up(h Interface, j int) {
  80         for {
  81                 i := (j - 1) / 2 // parent
  82                 if i == j || !h.Less(j, i) {
  83                         break
  84                 }
  85                 h.Swap(i, j)
  86                 j = i
  87         }
  88 }
  89
  90 func down(h Interface, i, n int) {
  91         for {
  92                 j1 := 2*i + 1
  93                 if j1 >= n || j1 < 0 { // j1 < 0 after int overflow
  94                         break
  95                 }
  96                 j := j1 // left child
  97                 if j2 := j1 + 1; j2 < n && !h.Less(j1, j2) {
  98                         j = j2 // = 2*i + 2  // right child
  99                 }
 100                 if !h.Less(j, i) {
 101                         break
 102                 }
 103                 h.Swap(i, j)
 104                 i = j
 105         }
 106 }