https://github.com/make-github-pseudonymous-again/js-search-tree-spec
:mag: Search tree specification for JavaScript
https://github.com/make-github-pseudonymous-again/js-search-tree-spec
Last synced: about 1 month ago
JSON representation
:mag: Search tree specification for JavaScript
- Host: GitHub
- URL: https://github.com/make-github-pseudonymous-again/js-search-tree-spec
- Owner: make-github-pseudonymous-again
- License: agpl-3.0
- Created: 2020-10-26T19:44:05.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2021-04-26T14:09:27.000Z (almost 5 years ago)
- Last Synced: 2025-01-18T15:53:40.972Z (about 1 year ago)
- Language: JavaScript
- Homepage: https://aureooms.github.io/js-search-tree-spec
- Size: 2.51 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
:mag: [@aureooms/js-search-tree-spec](https://make-github-pseudonymous-again.github.io/js-search-tree-spec)
==
Search tree specification for JavaScript.
See [docs](https://make-github-pseudonymous-again.github.io/js-search-tree-spec).
Parent is [@aureooms/js-bst](https://github.com/make-github-pseudonymous-again/js-bst).
```js
// eslint-disable-next-line ava/use-test
import ava from 'ava' ;
import * as spec from '@aureooms/js-search-tree-spec' ;
spec.test(
ava ,
{
name: "DummySearchTree" , // Name for the implementation
empty: compare => new spec.DummySearchTree(compare) , // Return an empty search tree using `compare` to order keys
from: (compare, iterable) => spec.DummySearchTree.from(compare, iterable) , // Return a search tree using `compare` to order keys initialized with the values in iterable
} ,
{
length : true , // Do the implementations maintain a `length` property?
lengths : [0, 1, 16, 17, 31, 32, 33, 63, 64, 65] , // Tree sizes to test.
}
) ;
```
[](https://raw.githubusercontent.com/make-github-pseudonymous-again/js-search-tree-spec/main/LICENSE)
[](https://www.npmjs.org/package/@aureooms/js-search-tree-spec)
[](https://travis-ci.org/make-github-pseudonymous-again/js-search-tree-spec/branches)
[](https://david-dm.org/make-github-pseudonymous-again/js-search-tree-spec)
[](https://david-dm.org/make-github-pseudonymous-again/js-search-tree-spec?type=dev)
[](https://github.com/make-github-pseudonymous-again/js-search-tree-spec/issues)
[](https://www.npmjs.org/package/@aureooms/js-search-tree-spec)
[](https://codeclimate.com/github/make-github-pseudonymous-again/js-search-tree-spec/issues)
[](https://codeclimate.com/github/make-github-pseudonymous-again/js-search-tree-spec/trends/churn)
[](https://codecov.io/gh/make-github-pseudonymous-again/js-search-tree-spec)
[](https://codeclimate.com/github/make-github-pseudonymous-again/js-search-tree-spec/trends/technical_debt)
[](https://make-github-pseudonymous-again.github.io/js-search-tree-spec//source.html)
[](https://bundlephobia.com/result?p=@aureooms/js-search-tree-spec)
## :newspaper: Description
This package contains a specification test suite for search tree
implementations such as
[@aureooms/js-red-black-tree](https://github.com/make-github-pseudonymous-again/js-red-black-tree),
[@aureooms/js-splay-tree](https://github.com/make-github-pseudonymous-again/js-splay-tree),
and
[@aureooms/js-avl-tree](https://github.com/make-github-pseudonymous-again/js-avl-tree).
## :woman_teacher: Specification
### :balance_scale: Definition of a `Ternary Comparator`
We choose to parameterize trees using ternary comparator functions rather that
key functions (as is done in Python for instance).
Comparator = ( x , x ) -> Number
Key = ( x ) -> String
compare( a , b ) < 0 <=> key( a ) < key( b )
compare( a , b ) = 0 <=> key( a ) = key( b )
compare( a , b ) > 0 <=> key( a ) > key( b )
#### Example of a `Ternary Comparator`
The following `Comparator` orders instances of `String`.
```js
const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
```
### Exposed tree constructors
No surprises here:
```js
const { from , empty } = SearchTree ;
```
### `empty(Comparator) -> SearchTree`
Create an empty search tree from a comparator function.
```js
let tree = empty( compare ) ;
```
### `from(Comparator, Iterable) -> Tree`
Create a search tree from a comparator function and an iterable.
```js
let tree = from( compare , 'abc' ) ;
```
### `Tree#length -> Number` (optional)
Returns the number of elements in the tree.
```js
if ( tree.length > 1 ) ...
```
### `Tree#isEmpty() -> Boolean`
Returns `true` if the tree is empty, `false` otherwise.
```js
return tree.isEmpty() ? 'empty' : 'not empty' ;
```
### `Tree#has(x) -> Boolean`
Returns `true` if the tree contains given element.
```js
if (tree.has(x)) ...
```
### Insertion
#### `Tree#insert(x) -> Reference`
Insert given element in the tree and returns optional reference.
```js
tree.insert('abc');
```
Could also be called `Tree#add` instead.
### Update
#### `Tree#update(x) -> Reference`
Update given element in the tree and returns optional reference.
```js
tree.insert({key: 'abc', value: 0});
tree.update({key: 'abc', value: 123});
```
### Removal
#### `Tree#removeFirst(x) -> Boolean`
Remove first occurrence of element. Returns optional boolean indicating if an
element was removed.
```js
tree.insert('x');
tree.insert('x');
tree.removeFirst('x');
```
#### `Tree#removeLast(x) -> Boolean`
Remove last occurrence of element. Returns optional boolean indicating if an
element was removed.
```js
tree.insert('x');
tree.insert('x');
tree.removeLast('x');
```
#### `Tree#removeAll(x) -> Boolean`
Remove all occurrences of element. Returns optional boolean indicating if an
element was removed.
```js
tree.insert('x');
tree.insert('x');
tree.removeAll('x');
```
#### `Tree#remove(x) -> Boolean`
Alias for `Tree#removeFirst`.
#### `Tree#delete(ref)`
Remove element given reference.
```js
let ref = tree.insert('abc');
tree.delete(ref);
```
Could also be called `Tree#unlink` instead. Leaving `Tree#delete` as an alias
for `Tree#removeFirst` or `Tree#removeAll` to mimic the `Set` API.
### Searching
#### `Tree#find(x) -> x`
#### `Tree#predecessor(x) -> x`
#### `Tree#successor(x) -> x`
#### `Tree#leftMost() -> x`
#### `Tree#rightMost() -> x`
### Merging
#### `Tree#meld(other)`
Merge two trees. Merged trees are destroyed.
```js
let a = from(compare, 'abc');
let b = from(compare, '123');
a.meld(b);
```
### Split
#### `Tree#split(x) -> [Tree, x, Tree]`
Split a tree at `x` such that
```js
const [left, key, right] = tree.split(x);
assert(compare(key, x) === 0);
assert(isBinarySearchTree({key, left, right}));
```
### Visit
#### `Tree#[Symbol.iterator]() -> Iterator`
#### `Tree#items() -> Iterator`
Alias for `Tree#[Symbol.iterator]()`.
#### `Tree#reversed() -> Iterator`
#### `Tree#rangeIE(left, right) -> Iterator`
#### `Tree#rangeII(left, right) -> Iterator`
#### `Tree#rangeEI(left, right) -> Iterator`
#### `Tree#rangeEE(left, right) -> Iterator`
#### `Tree#range(left, right) -> Iterator`
Alias for `Tree#rangeIE(left, right) -> Iterator`.