proposal: container/heap generic example

[rossb83]

Now that generics are sorted out the documentation example priority queue here https://pkg.go.dev/container/heap should include the use of generics like below

type PriorityQueue[K comparable, P cmp.Ordered] []*Item[K, P]

type Item[K comparable, P cmp.Ordered] struct {
	value    K
	priority P
	index    int
}

func (pq PriorityQueue[_, _]) Len() int {
	return len(pq)
}

func (pq PriorityQueue[_, _]) Less(i, j int) bool {
	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[K, P]) Push(x any) {
	n := len(*pq)
	item := x.(*Item[K, P])
	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
}

Beyond this I feel there is a lot of machinery required to implement the heap interface (like above) and wonder if any work can/should be done to make this simpler.

[cespare]

Instead of adding documentation, we should add an implementation (see #47632).

[seankhliao]

Duplicate of #47632