▼ |  | Data: Data Structures

1 | Imperative Queues
2 | Growable Vectors
3 | Orders and Ordered Dictionaries
4 | Splay Trees
5 | Skip Lists
6 | Interval Maps
7 | Binary Heaps
8 | Integer Sets
9 | Bit Vectors
10 | Union-Find: Sets with only Canonical Elements
11 | Enumerations

On this page:

make-heap
heap?
heap-count
heap-add!
heap-add-all!
heap-min
heap-remove-min!
heap-remove!
vector->heap
heap->vector
heap-copy
in-heap/ consume!
in-heap
heap-sort!

6.8
top ← prev up next →

### 7`` Binary Heaps

Ryan Culpepper <ryanc@racket-lang.org>

(require data/heap) | package: data-lib

Binary heaps are a simple implementation of priority queues.

Operations on binary heaps are not thread-safe.

> procedure (make-heap <=?) → heap?
> <=? : (-> any/c any/c any/c)

Makes a new empty heap using <=? to order elements.

Examples:

> > (define a-heap-of-strings (make-heap string<=?))
> > a-heap-of-strings
> #<heap>
> ; With structs:
> > (struct node (name val))
> > (define (node<=? x y)
> (<= (node-val x) (node-val y)))
> > (define a-heap-of-nodes (make-heap node<=?))
> > a-heap-of-nodes
> #<heap>

> procedure (heap? x) → boolean?
> x : any/c

Returns #t if x is a heap, #f otherwise.

Examples:

> > (heap? (make-heap <=))
> #t
> > (heap? "I am not a heap")
> #f

> procedure (heap-count h) → exact-nonnegative-integer?
> h : heap?

Returns the number of elements in the heap.

Examples:

> > (define a-heap (make-heap <=))
> > (heap-add-all! a-heap '(7 3 9 1 13 21 15 31))
> > (heap-count a-heap)
> 8

> procedure (heap-add! h v ...) → void?
> h : heap?
> v : any/c

Adds each v to the heap.

Examples:

> > (define a-heap (make-heap <=))
> > (heap-add! a-heap 2009 1009)

> procedure (heap-add-all! h v) → void?
> h : heap?
> v : (or/c list? vector? heap?)

Adds each element contained in v to the heap, leaving v unchanged.

Examples:

> > (define heap-1 (make-heap <=))
> > (define heap-2 (make-heap <=))
> > (define heap-12 (make-heap <=))
> > (heap-add-all! heap-1 '(3 1 4 1 5 9 2 6))
> > (heap-add-all! heap-2 #(2 7 1 8 2 8 1 8))
> > (heap-add-all! heap-12 heap-1)
> > (heap-add-all! heap-12 heap-2)
> > (heap-count heap-12)
> 16

> procedure (heap-min h) → any/c
> h : heap?

Returns the least element in the heap h, according to the heap’s ordering. If the heap is empty, an exception is raised.

Examples:

> > (define a-heap (make-heap string<=?))
> > (heap-add! a-heap "sneezy" "sleepy" "dopey" "doc"
> "happy" "bashful" "grumpy")
> > (heap-min a-heap)
> "bashful"
> ; Taking the min of the empty heap is an error:
> > (heap-min (make-heap <=))
> heap-min: empty heap

> procedure (heap-remove-min! h) → void?
> h : heap?

Removes the least element in the heap h. If the heap is empty, an exception is raised.

Examples:

> > (define a-heap (make-heap string<=?))
> > (heap-add! a-heap "fili" "fili" "oin" "gloin" "thorin"
> "dwalin" "balin" "bifur" "bofur"
> "bombur" "dori" "nori" "ori")
> > (heap-min a-heap)
> "balin"
> > (heap-remove-min! a-heap)
> > (heap-min a-heap)
> "bifur"

> procedure (heap-remove! h v [#:same? same?]) → void?
> h : heap?
> v : any/c
> same? : (-> any/c any/c any/c) = equal?

Removes v from the heap h if it exists.

Examples:

> > (define a-heap (make-heap string<=? string=?))
> make-heap: arity mismatch;
> the expected number of arguments does not match the given
> number
> expected: 1
> given: 2
> arguments...:
> #<procedure:string<=?>
> #<procedure:string=?>
> > (heap-add! a-heap "a" "b" "c")
> > (heap-remove! a-heap "b")
> > (for/list ([a (in-heap a-heap)]) a)
> '("a"
> "bifur"
> "bofur"
> "bombur"
> "c"
> "dori"
> "dwalin"
> "fili"
> "fili"
> "gloin"
> "nori"
> "oin"
> "ori"
> "thorin")

> procedure (vector->heap <=? items) → heap?
> <=? : (-> any/c any/c any/c)
> items : vector?

Builds a heap with the elements from items. The vector is not modified.

Examples:

> > (struct item (val frequency))
> > (define (item<=? x y)
> (<= (item-frequency x) (item-frequency y)))
> > (define some-sample-items
> (vector (item #\a 17) (item #\b 12) (item #\c 19)))
> > (define a-heap (vector->heap item<=? some-sample-items))

> procedure (heap->vector h) → vector?
> h : heap?

Returns a vector containing the elements of heap h in the heap’s order. The heap is not modified.

Examples:

> > (define word-heap (make-heap string<=?))
> > (heap-add! word-heap "pile" "mound" "agglomerate" "cumulation")
> > (heap->vector word-heap)
> '#("agglomerate" "cumulation" "mound" "pile")

> procedure (heap-copy h) → heap?
> h : heap?

Makes a copy of heap h.

Examples:

> > (define word-heap (make-heap string<=?))
> > (heap-add! word-heap "pile" "mound" "agglomerate" "cumulation")
> > (define a-copy (heap-copy word-heap))
> > (heap-remove-min! a-copy)
> > (heap-count word-heap)
> 4
> > (heap-count a-copy)
> 3

> procedure (in-heap/consume! heap) → sequence?
> heap : heap?

Returns a sequence equivalent to heap, maintaining the heap’s ordering. The heap is consumed in the process. Equivalent to repeated calling heap-min, then heap-remove-min!.

Examples:

> > (define h (make-heap <=))
> > (heap-add-all! h '(50 40 10 20 30))
> > (for ([x (in-heap/consume! h)])
> (displayln x))
> 10
> 20
> 30
> 40
> 50
> > (heap-count h)
> 0

> procedure (in-heap heap) → sequence?
> heap : heap?

Returns a sequence equivalent to heap, maintaining the heap’s ordering. Equivalent to in-heap/consume! except the heap is copied first.

Examples:

> > (define h (make-heap <=))
> > (heap-add-all! h '(50 40 10 20 30))
> > (for ([x (in-heap h)])
> (displayln x))
> 10
> 20
> 30
> 40
> 50
> > (heap-count h)
> 5

> procedure (heap-sort! v <=?) → void?
> v : (and/c vector? (not/c immutable?))
> <=? : (-> any/c any/c any/c)

Sorts vector v using the comparison function <=?.

Examples:

> > (define terms (vector "batch" "deal" "flock" "good deal" "hatful" "lot"))
> > (heap-sort! terms string<=?)
> > terms
> '#("batch" "deal" "flock" "good deal" "hatful" "lot")

top ← prev up next →