Documentation
¶
Overview ¶
Package heap provides heap operations for any type that implements heap.Interface. A heap is a tree with the property that each node is the minimum-valued node in its subtree.
The minimum element in the tree is the root, at index 0.
A heap is a common way to implement a priority queue. To build a priority queue, implement the Heap interface with the (negative) priority as the ordering for the Less method, so Push adds items while Pop removes the highest-priority item from the queue. The Examples include such an implementation; the file example_pq_test.go has the complete source.
Example (HeapPriorityQueue) ¶
This example creates a priority queue with some items, adds and manipulates an item, and then removes the items in priority order.
// This example demonstrates a priority queue built using a Heap.
package main
import (
"fmt"
"github.com/cespare/next/container/heap"
)
// update modifies the priority and value of an Item in the queue.
func update(pq *heap.Heap[*Item], item *Item, value string, priority int) {
item.value = value
item.priority = priority
pq.Fix(item.index)
}
// This example creates a priority queue with some items, adds and manipulates an item,
// and then removes the items in priority order.
func main() {
// Some items and their priorities.
items := map[string]int{
"banana": 3, "apple": 2, "pear": 4,
}
// Create a priority queue, put the items in it, and
// establish the priority queue (heap) invariants.
pq := heap.New(func(item0, item1 *Item) bool {
return item0.priority > item1.priority
})
pq.SetIndex = func(item *Item, i int) { item.index = i }
var s []*Item
i := 0
for value, priority := range items {
s = append(s, &Item{
value: value,
priority: priority,
index: i,
})
i++
}
pq.Init(s)
// Insert a new item and then modify its priority.
item := &Item{
value: "orange",
priority: 1,
}
pq.Push(item)
update(pq, item, item.value, 5)
// Take the items out; they arrive in decreasing priority order.
for pq.Len() > 0 {
item := pq.Pop()
fmt.Printf("%.2d:%s ", item.priority, item.value)
}
}
Output: 05:orange 04:pear 03:banana 02:apple
Example (IntHeap) ¶
This example inserts several ints into an IntHeap, checks the minimum, and removes them in order of priority.
// This example demonstrates an integer heap built using the heap interface.
package main
import (
"fmt"
"github.com/cespare/next/container/heap"
)
// An IntHeap is a min-heap of ints.
type IntHeap []int
func (h IntHeap) Len() int { return len(h) }
func (h IntHeap) Less(i, j int) bool { return h[i] < h[j] }
func (h IntHeap) Swap(i, j int) { h[i], h[j] = h[j], h[i] }
func (h *IntHeap) Push(x any) {
// Push and Pop use pointer receivers because they modify the slice's length,
// not just its contents.
*h = append(*h, x.(int))
}
func (h *IntHeap) Pop() any {
old := *h
n := len(old)
x := old[n-1]
*h = old[0 : n-1]
return x
}
// This example inserts several ints into an IntHeap, checks the minimum,
// and removes them in order of priority.
func main() {
h := &IntHeap{2, 1, 5}
heap.Init(h)
heap.Push(h, 3)
fmt.Printf("minimum: %d\n", (*h)[0])
for h.Len() > 0 {
fmt.Printf("%d ", heap.Pop(h))
}
}
Output: minimum: 1 1 2 3 5
Example (PriorityQueue) ¶
This example creates a PriorityQueue with some items, adds and manipulates an item, and then removes the items in priority order.
// This example demonstrates a priority queue built using the heap interface.
package main
import (
"fmt"
"github.com/cespare/next/container/heap"
)
// An Item is something we manage in a priority queue.
type Item struct {
value string // The value of the item; arbitrary.
priority int // The priority of the item in the queue.
// The index is needed by update and is maintained by the heap.Interface methods.
index int // The index of the item in the heap.
}
// A PriorityQueue implements heap.Interface and holds Items.
type PriorityQueue []*Item
func (pq PriorityQueue) Len() int { return len(pq) }
func (pq PriorityQueue) Less(i, j int) bool {
// We want Pop to give us the highest, not lowest, priority so we use greater than here.
return pq[i].priority > pq[j].priority
}
func (pq PriorityQueue) Swap(i, j int) {
pq[i], pq[j] = pq[j], pq[i]
pq[i].index = i
pq[j].index = j
}
func (pq *PriorityQueue) Push(x any) {
n := len(*pq)
item := x.(*Item)
item.index = n
*pq = append(*pq, item)
}
func (pq *PriorityQueue) Pop() any {
old := *pq
n := len(old)
item := old[n-1]
old[n-1] = nil // avoid memory leak
item.index = -1 // for safety
*pq = old[0 : n-1]
return item
}
// update modifies the priority and value of an Item in the queue.
func (pq *PriorityQueue) update(item *Item, value string, priority int) {
item.value = value
item.priority = priority
heap.Fix(pq, item.index)
}
// This example creates a PriorityQueue with some items, adds and manipulates an item,
// and then removes the items in priority order.
func main() {
// Some items and their priorities.
items := map[string]int{
"banana": 3, "apple": 2, "pear": 4,
}
// Create a priority queue, put the items in it, and
// establish the priority queue (heap) invariants.
pq := make(PriorityQueue, len(items))
i := 0
for value, priority := range items {
pq[i] = &Item{
value: value,
priority: priority,
index: i,
}
i++
}
heap.Init(&pq)
// Insert a new item and then modify its priority.
item := &Item{
value: "orange",
priority: 1,
}
heap.Push(&pq, item)
pq.update(item, item.value, 5)
// Take the items out; they arrive in decreasing priority order.
for pq.Len() > 0 {
item := heap.Pop(&pq).(*Item)
fmt.Printf("%.2d:%s ", item.priority, item.value)
}
}
Output: 05:orange 04:pear 03:banana 02:apple
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Fix ¶
Fix re-establishes the heap ordering after the element at index i has changed its value. Changing the value of the element at index i and then calling Fix is equivalent to, but less expensive than, calling Remove(h, i) followed by a Push of the new value. The complexity is O(log n) where n = h.Len().
func Init ¶
func Init(h Interface)
Init establishes the heap invariants required by the other routines in this package. Init is idempotent with respect to the heap invariants and may be called whenever the heap invariants may have been invalidated. The complexity is O(n) where n = h.Len().
func Pop ¶
Pop removes and returns the minimum element (according to Less) from the heap. The complexity is O(log n) where n = h.Len(). Pop is equivalent to Remove(h, 0).
Types ¶
type Heap ¶
type Heap[E any] struct { // Less is the comparison function given to New. // If a Heap is created without calling New, // Less must be set before the heap is used. // Less should not be changed after the heap has been used. Less func(E, E) bool // SetIndex is an optional function to be called // when updating the position of any heap element within the slice, // including during Init or Push. // // When an element is removed from the heap by Pop or Remove, // the index function is called with the invalid index -1 // to signify that the element is no longer within the slice. // // If used, SetIndex should be set before calling heap methods and // should not be changed after that. SetIndex func(E, int) // contains filtered or unexported fields }
A Heap is a min-heap backed by a slice.
func (*Heap[E]) Fix ¶
Fix re-establishes the heap ordering after the element at index i has changed its value. Changing the value of the element at index i and then calling Fix is equivalent to, but less expensive than, calling h.Remove(i) followed by a Push of the new value. The complexity is O(log n) where n = h.Len().
func (*Heap[E]) Init ¶
func (h *Heap[E]) Init(s []E)
Init sets the contents of the heap to the given slice and establishes the heap invariants required by the other routines in this package. Init is idempotent with respect to the heap invariants and may be called whenever the heap invariants may have been invalidated. The complexity is O(n) where n = len(s).
func (*Heap[E]) Peek ¶
func (h *Heap[E]) Peek() E
Peek returns the minimum element (according to the less function) in the heap. Peek panics if the heap is empty. The complexity is O(1).
func (*Heap[E]) Pop ¶
func (h *Heap[E]) Pop() E
Pop removes and returns the minimum element (according to the less function) from the heap. Pop panics if the heap is empty. The complexity is O(log n) where n = h.Len().
func (*Heap[E]) Push ¶
func (h *Heap[E]) Push(elem E)
Push pushes an element onto the heap. The complexity is O(log n) where n = h.Len().
type Interface ¶
type Interface interface {
sort.Interface
Push(x any) // add x as element Len()
Pop() any // remove and return element Len() - 1.
}
The Interface type describes the requirements for a type using the routines in this package. Any type that implements it may be used as a min-heap with the following invariants (established after Init has been called or if the data is empty or sorted):
!h.Less(j, i) for 0 <= i < h.Len() and 2*i+1 <= j <= 2*i+2 and j < h.Len()
Note that Push and Pop in this interface are for package heap's implementation to call. To add and remove things from the heap, use heap.Push and heap.Pop.
Source Files