From d76b01b4f1d67c98f66418d27d775f8a86934751 Mon Sep 17 00:00:00 2001 From: Philipp Schiffmann Date: Fri, 18 Jun 2021 09:28:24 +0200 Subject: [PATCH 1/3] Add API docs to README --- README.md | 47 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index b4d0da9..0ca669d 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,50 @@ -## flatqueue [![Build Status](https://travis-ci.com/mourner/flatqueue.svg?branch=master)](https://travis-ci.com/mourner/flatqueue) +# flatqueue [![Build Status](https://travis-ci.com/mourner/flatqueue.svg?branch=master)](https://travis-ci.com/mourner/flatqueue) A very fast binary heap priority queue in JavaScript. Similar to [tinyqueue](https://github.com/mourner/tinyqueue/), -but stores the queue as two flat arrays of item ids and their numeric priority values respectively +but stores the queue as two flat arrays of items and their numeric priority values respectively (without a way to specify a comparator function). This makes the queue more limited, but several times faster. ```js -const q = new FlatQueue(); +const queue = new FlatQueue(); -for (let i = 0; i < items.length; i++) { - q.push(i, items[i].value); // push an item by passing its id and value +const data = "Lorem ipsum dolor sit amet consetetur sadipscing elitr".split(" "); +for (const word of data) { + const priority = word.length; + queue.push(word, priority); } -q.peekValue(); // top item value -q.peek(); // top item index -q.pop(); // remove and return the top item index +// Iterate through words from shortest to longest. +while (queue.length !== 0) { + console.log(queue.pop()); +} ``` + +## API + +### `FlatQueue.push(item, priority)` + +Adds `item` to the queue with the specified `priority`. + +`priority` must be a number. Items are sorted and returned from low to high priority. +Multiple items with the same priority value can be added to the queue, but there is no guaranteed order between these items. + +### `FlatQueue.pop()` + +Removes and returns the item from the head of this queue, which is one of the items with the lowest priority. +If this queue is empty, returns `undefined`. + +### `FlatQueue.peek()` + +Returns the item from the head of this queue without removing it. +If this queue is empty, returns `undefined`. + +### `FlatQueue.peekValue()` + +Returns the priority value of the item at the head of this queue without removing it. +If this queue is empty, returns `undefined`. + +### `FlatQueue.length` + +Number of items in the queue. Readonly. From fbd9dbf8c5d6fd91d980cb8855ca523bc2796826 Mon Sep 17 00:00:00 2001 From: Philipp Schiffmann Date: Fri, 18 Jun 2021 09:49:11 +0200 Subject: [PATCH 2/3] Add docs for clear(), shrink() --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index 0ca669d..f10ec78 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,14 @@ If this queue is empty, returns `undefined`. Returns the priority value of the item at the head of this queue without removing it. If this queue is empty, returns `undefined`. +### `FlatQueue.clear()` + +Removes all items from the queue. + +### `FlatQueue.shrink()` + +Shrinks the internal arrays to `this.length`. + ### `FlatQueue.length` Number of items in the queue. Readonly. From 577424d3d1b497d1914c6d72a8ed0597cbcf36c1 Mon Sep 17 00:00:00 2001 From: Philipp Schiffmann Date: Sun, 20 Jun 2021 19:08:33 +0200 Subject: [PATCH 3/3] Update docs --- README.md | 26 +++++++++++++++----------- index.d.ts | 5 +++++ 2 files changed, 20 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index f10ec78..e84098c 100644 --- a/README.md +++ b/README.md @@ -7,18 +7,19 @@ but stores the queue as two flat arrays of items and their numeric priority valu This makes the queue more limited, but several times faster. ```js -const queue = new FlatQueue(); - -const data = "Lorem ipsum dolor sit amet consetetur sadipscing elitr".split(" "); -for (const word of data) { - const priority = word.length; - queue.push(word, priority); +const q = new FlatQueue(); + +for (let i = 0; i < items.length; i++) { + // Push an item index and its priority value. + // You can push other values as well, for example the item itself. However, + // storing only integers enables certain performance optimizations in some + // JavaScript engines. + q.push(i, items[i].value); } -// Iterate through words from shortest to longest. -while (queue.length !== 0) { - console.log(queue.pop()); -} +q.peekValue(); // Read top item priority value +q.peek(); // Read top item index +q.pop(); // Remove and return the top item index ``` ## API @@ -28,7 +29,7 @@ while (queue.length !== 0) { Adds `item` to the queue with the specified `priority`. `priority` must be a number. Items are sorted and returned from low to high priority. -Multiple items with the same priority value can be added to the queue, but there is no guaranteed order between these items. +Multiple items with the same priority value can be added to the queue, but the queue is not stable (items with the same priority are not guaranteed to be popped in iteration order). ### `FlatQueue.pop()` @@ -53,6 +54,9 @@ Removes all items from the queue. Shrinks the internal arrays to `this.length`. +`pop()` and `clear()` calls don't free memory automatically to avoid unnecessary resize operations. +This also means that items that have been added to the queue can't be garbage collected until a new item is pushed in their place, or this method is called. + ### `FlatQueue.length` Number of items in the queue. Readonly. diff --git a/index.d.ts b/index.d.ts index 38b5222..d9681dc 100644 --- a/index.d.ts +++ b/index.d.ts @@ -41,6 +41,11 @@ export default class FlatQueue { /** * Shrinks the internal arrays to `this.length`. + * + * `pop()` and `clear()` calls don't free memory automatically to avoid + * unnecessary resize operations. This also means that items that have been + * added to the queue can't be garbage collected until a new item is pushed + * in their place, or this method is called. */ shrink(): void; }