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