Skip to content

Commit ad425c0

Browse files
committed
New: BinaryHeap implementation
1 parent 949af15 commit ad425c0

File tree

4 files changed

+805
-0
lines changed

4 files changed

+805
-0
lines changed
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# JavaScript Binary Heap Class
2+
3+
by [Nicholas C. Zakas](https://humanwhocodes.com)
4+
5+
If you find this useful, please consider supporting my work with a [donation](https://humanwhocodes.com/donate).
6+
7+
## Overview
8+
9+
A JavaScript implementation of a binary heap. This class uses the conventions of built-in JavaScript collection objects, such as:
10+
11+
1. There is a `[Symbol.iterator]` method so each instance is iterable.
12+
1. The `size` getter property instead of a `length` data property to indicate that the size of the list is dynamically counted rather than stored.
13+
1. Defining a `values()` generator method.
14+
1. Using `includes()` instead of `contains()`.
15+
16+
## Usage
17+
18+
Use CommonJS to get access to the `BinaryHeap` constructor:
19+
20+
```js
21+
const { BinaryHeap } = require("@humanwhocodes/binary-heap");
22+
```
23+
24+
Each instance of `BinaryHeap` has the following properties and methods:
25+
26+
```js
27+
const heap = new BinaryHeap();
28+
29+
// add an item to the end
30+
heap.add("foo");
31+
32+
// get the minimum value without removing
33+
let value = heap.peek();
34+
35+
// get the minimum value and remove
36+
let value = heap.poll();
37+
38+
// get the number of items
39+
let count = heap.size;
40+
41+
// does the value exist in the heap?
42+
let found = heap.includes(5);
43+
44+
// convert to an array using iterators
45+
let array1 = [...heap.values()];
46+
let array2 = [...heap];
47+
48+
// remove all items
49+
heap.clear();
50+
```
51+
52+
By default, the `BinaryHeap` class is a min heap designed to work with numbers. You can change the comparator used to determine ordering by passing a function into the constructor, such as:
53+
54+
```js
55+
// create a max numeric heap
56+
let heap = new BinaryHeap((a, b) => b - a);
57+
```
58+
59+
The comparator function uses the same format as comparator functions for JavaScript arrays, two values are passed in and you must return:
60+
61+
* A negative number if the first value should come before the second
62+
* Zero if the ordering of the two values should remain unchanged
63+
* A positive number if the first value should come after the second
64+
65+
## Note on Code Style
66+
67+
You may find the code style of this module to be overly verbose with a lot of comments. That is intentional, as the primary use of this module is intended to be for educational purposes. There are frequently more concise ways of implementing the details of this class, but the more concise ways are difficult for newcomers who are unfamiliar with linked lists as a concept or JavaScript as a whole.
68+
69+
## Issues and Pull Requests
70+
71+
As this is part of series of tutorials I'm writing, only bug fixes will be accepted. No new functionality will be added to this module.
72+
73+
## License
74+
75+
MIT

0 commit comments

Comments
 (0)