Next: Immutable deques, Previous: Cache, Up: Library modules - Utilities [Contents][Index]

`data.heap`

- Heap- Module:
**data.heap** -
A heap is a data container that allows efficient retrieval of the minimum or maximum entry. Unlike a

`<tree-map>`

(see Treemaps), which always keeps all entries in order, a heap only cares the minimum or the maximum of the current set; the other entries are only partially ordered, and reordered when the minimu/maximum entry is removed. Hence it is more efficient than a treemap if all you need is minimum/maximum value. Besides binary heaps can store entries in packed, memory-efficient way.

- Class:
**<binary-heap>** -
{

`data.heap`} An implementation of a binary heap. Internally it uses min-max heap, so that you can find both minimum and maximum value in O(1). Pushing a new value and popping the minimum/maximum value are both O(log n).It also stores its values in a flat vector, a lot more compact than a general tree structure that needs a few pointers per node. By default it uses a sparse vector for the backing storage, allowing virtually unlimited capacity (see Sparse vectors). But you can use an ordinal vector or a uniform vector as a backing storage instead.

A binary heap isn’t MT-safe structure; you must put it in atom or use mutexes if multiple threads can access to it (see Synchronization primitives).

- Function:
**make-binary-heap***:key comparator storage key* {

`data.heap`} Creates and returns a new binary heap.The

`comparator`keyword argument specifies how to compare the entries. It must have comparison procedure or ordering predicate. The default is`default-comparator`

. See Basic comparators, for the details of comparators.The

`storage`keyword argument gives alternative backing storage. It must be either a vector, a uniform vector, or an instance of a sparse vector (see Sparse vectors). The default is an instance of`<sparse-vector>`

. If you pass a vector or a uniform vector, it determines the maximum number of elements the heap can hold. The heap won’t be extend the storage once it gets full.The

`key`keyword argument must be a procedure; it is applied on each entry before comparison. Using key procedure allows you to store auxiliary data other than the actual value to be compared. The following example shows the entries are compared by their`car`

’s:(define *heap* (make-binary-heap :key car)) (binary-heap-push! *heap* (cons 1 'a)) (binary-heap-push! *heap* (cons 3 'b)) (binary-heap-push! *heap* (cons 1 'c)) (binary-heap-find-min *heap*) ⇒ (1 . c) (binary-heap-find-max *heap*) ⇒ (3 . b)

- Function:
**build-binary-heap***storage :key comparator key num-entries* {

`data.heap`} Create a heap from the data in`storage`, and returns it. (Sometimes this operation is called*heapify*.) This allows you to create a heap without allocating a new storage. The`comparator`and`key`arguments are the same as`make-binary-heap`

.`Storage`must be either a vector, a uniform vector, or an instance of a sparse vector. The storage is modified to satisfy the heap property, and will be used as the backing storage of the created heap. Since the storage will be owned by the heap, you shouldn’t modify the storage later.The storage supposed to have keys from index 0 below

`num-entries`. If`num-entries`is omitted or`#f`

, entire vector or uniform vector, or up to`sparse-vector-num-entries`

on the sparse vector, is heapified.

- Function:
**binary-heap-copy***heap* {

`data.heap`} Copy the heap. The backing storage is also copied.

- Function:
**binary-heap-clear!***heap* {

`data.heap`} Empty the heap.

- Function:
**binary-heap-num-entries***heap* {

`data.heap`} Returns the current number of entries in the heap.

- Function:
**binary-heap-empty?***heap* {

`data.heap`} Returns`#t`

if the heap is empty,`#f`

otherwise.

- Function:
**binary-heap-push!***heap item* {

`data.heap`} Insert`item`into the`heap`. This is O(log n) operation. If the heap is already full, an error is raised.

- Function:
**binary-heap-find-min***heap :optional fallback* - Function:
**binary-heap-find-max***heap :optional fallback* {

`data.heap`} Returns the minimum and maximum entry of the heap, respectively. The heap will be unmodified. This is O(1) operation.If the heap is empty,

`fallback`is returned when it is provided, or an error is signaled.

- Function:
**binary-heap-pop-min!***heap* - Function:
**binary-heap-pop-max!***heap* {

`data.heap`} Removes the minimum and maximum entry of the heap and returns it, respectively. O(log n) operation. If the heap is empty, an error is signaled.

The following procedures are not heap operations, but provided for the convenience.

- Function:
**binary-heap-swap-min!***heap item* - Function:
**binary-heap-swap-max!***heap item* {

`data.heap`} These are operationally equivalent to the followings, respectively:(begin0 (binary-heap-pop-min! heap) (binary-heap-push! heap item)) (begin0 (binary-heap-pop-max! heap) (binary-heap-push! heap item))

However, those procedures are slightly efficient, using heap property maintaining procedure only once per function call.

- Function:
**binary-heap-find***pred heap :optional failure* {

`data.heap`} Returns an item in the heap that satisfies`pred`. If there are more than one item that satisfy`pred`, any one of them can be returned. If no item satisfy`pred`, the thunk`failure`is called, whose default is`(^[] #f)`

. This is O(n) operation.Note: The argument order used to be

`(binary-heap-find heap pred)`

until 0.9.10. We changed it to align other *-find procedures. The old argument order still work for the backward compatibility, but the new code should use the current order.

- Function:
**binary-heap-remove!***heap pred* {

`data.heap`} Remove all items in the heap that satisfy`pred`. This is O(n) operation.

- Function:
**binary-heap-delete!***heap item* {

`data.heap`} Delete all items in the heap that are equal to`item`, in terms of the heap’s comparator and key procedure. This is O(n) operation.Note that the key procedure is applied to

`item`as well before comparison.

Next: Immutable deques, Previous: Cache, Up: Library modules - Utilities [Contents][Index]

DRAFT