Source file src/pkg/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	// highest-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_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(i, j) {
    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 {
    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(i, j) {
   101				break
   102			}
   103			h.Swap(i, j)
   104			i = j
   105		}
   106	}