Run Format

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	// 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 j = 2*i+1 or 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			down(h, i, n)
    76			up(h, i)
    77		}
    78		return h.Pop()
    79	}
    80	
    81	// Fix reestablishes the heap ordering after the element at index i has changed its value.
    82	// Changing the value of the element at index i and then calling Fix is equivalent to,
    83	// but less expensive than, calling Remove(h, i) followed by a Push of the new value.
    84	// The complexity is O(log(n)) where n = h.Len().
    85	func Fix(h Interface, i int) {
    86		down(h, i, h.Len())
    87		up(h, i)
    88	}
    89	
    90	func up(h Interface, j int) {
    91		for {
    92			i := (j - 1) / 2 // parent
    93			if i == j || !h.Less(j, i) {
    94				break
    95			}
    96			h.Swap(i, j)
    97			j = i
    98		}
    99	}
   100	
   101	func down(h Interface, i, n int) {
   102		for {
   103			j1 := 2*i + 1
   104			if j1 >= n || j1 < 0 { // j1 < 0 after int overflow
   105				break
   106			}
   107			j := j1 // left child
   108			if j2 := j1 + 1; j2 < n && !h.Less(j1, j2) {
   109				j = j2 // = 2*i + 2  // right child
   110			}
   111			if !h.Less(j, i) {
   112				break
   113			}
   114			h.Swap(i, j)
   115			i = j
   116		}
   117	}

View as plain text