atomic-fns 0.3.1 → 0.3.3

package/core/collections/SortedTree.ts

@@ -0,0 +1,160 @@
+import { Comparer } from '../operators/index.js'
+import { Mapping } from './abc.js'
+import { BTree } from './BTree.js'
+
+/**
+ * A `SortedTree` is a map that holds key value pairs in sorted orders of keys. Any primitive value (and objects that implement a `compare` or `lt` methods) can be used as keys or values.
+ * @see {@link Operators.compare}
+ * @see {@link Operators.lt}
+ * @template K, V
+ */
+export class SortedTree<K, V> extends Mapping<K, V> {
+  private readonly store: BTree<K, V>
+
+  /**
+   * Creates a new `SortedTree` object.
+   * @param {Iterable<[K, V]>} [iterable] Initialize the tree with entries.
+   * @param {Comparer} [compareFn] The `compare` function to sort keys.
+   */
+  constructor(iterable?: Iterable<[K, V]>, compareFn?: Comparer) {
+    super()
+    this.store = new BTree<K, V>(iterable, compareFn)
+  }
+
+  /**
+   * Adds a new `key` with a `null` value.
+   * @param {K} key
+   * @returns {this} Returns the Tree object.
+   */
+  add(key: K) {
+    this.store.set(key, null as V)
+    return this
+  }
+
+  /**
+   * Returns the value associated with the `key` or `undefined`.
+   * @param {K} key
+   * @returns {?V} The key value or `undefined`.
+   */
+  get(key: K) {
+    return this.store.get(key)
+  }
+
+  /**
+   * Sets the value for the given `key`.
+   * @param {K} key
+   * @param {V} value
+   * @returns {this} Returns the Tree object.
+   */
+  set(key: K, value: V) {
+    this.store.set(key, value)
+    return this
+  }
+
+  /**
+   * Returns the smallest key in the tree.
+   * @returns {?K}
+   */
+  min() {
+    return this.store.minKey()
+  }
+
+  /**
+   * Returns the largest key in the tree.
+   * @returns {?K}
+   */
+  max() {
+    return this.store.maxKey()
+  }
+
+  /**
+   * Returns `true` if the `key` existed in the tree and was removed.
+   * @param {K} key
+   * @returns {boolean} `true` if key was removed, otherwise `false`.
+   */
+  delete(key: K) {
+    return this.store.remove(key)
+  }
+
+  /**
+   * Removes all key/value pairs in the tree.
+   */
+  clear() {
+    return this.store.clear()
+  }
+
+  /**
+   * Freezes the tree which prevents adding, updating or removing any keys.
+   * @returns {this}
+   */
+  freeze() {
+    this.store.freeze()
+    return this
+  }
+
+  /**
+   * Returns a new iterator of `[K, V]` pairs in reverse order of keys.
+   * @returns {Iterable<[K, V]>}
+   */
+  reversed() {
+    return this.store.reversed()
+  }
+
+  /**
+   * Returns the total key/value pairs in the tree.
+   * @returns {number}
+   */
+  get size() {
+    return this.store.size
+  }
+
+  /**
+   * Check if there are no key/value pairs in the tree.
+   * @returns {boolean} `true` if is empty.
+   */
+  empty() {
+    return this.store.empty()
+  }
+
+  /**
+   * Returns `true` if the `key` exists in the tree.
+   * @param {K} key
+   * @returns {boolean} `true` if key is found, otherwise `false`.
+   */
+  contains(key: K) {
+    return this.store.contains(key)
+  }
+
+  /**
+   * Returns `true` if the `key` exists in the tree.
+   * @param {K} key
+   * @returns {boolean} `true` if key is found, otherwise `false`.
+   */
+  has(key: K) {
+    return this.store.contains(key)
+  }
+
+  /**
+   * Returns a new iterator of all **ordered** keys in the tree.
+   * @returns {Iterable<K>}
+   */
+  keys() {
+    return this.store.keys()
+  }
+
+  /**
+   * Returns a new iterator of all values **ordered** by their keys.
+   * @returns {Iterable<V>}
+   */
+  values() {
+    return this.store.values()
+  }
+
+  /**
+   * Returns a new iterator of all key value pairs **ordered** by their keys.
+   * @returns {Iterable<[K, V]>}
+   */
+  entries() {
+    return this.store.entries()
+  }
+}

package/core/collections/SplayTree.d.ts

@@ -0,0 +1,105 @@
+import { Comparer } from '../operators/index.js';
+import { Mapping } from './abc.js';
+/**
+ * Base SplayTree node class.
+ * @private
+ */
+declare class Node<K = any, V = any> {
+    key: K;
+    value: V;
+    left?: Node<K, V>;
+    right?: Node<K, V>;
+    constructor(key: K, value: V);
+    get height(): any;
+}
+/**
+ * A splay tree is a *self-balancing binary* search tree with the additional property that recently accessed elements are quick to access again.
+ * Insertion, look-up and removal in O(log n) *amortized* time.
+ * For many patterns of non-random operations splay trees can take better than logarithmic time, without requiring advance knowledge of the pattern.
+ * @see {@link https://en.wikipedia.org/wiki/Splay_tree Splay tree}
+ * @see {@link https://web.archive.org/web/20220930173835/http://www14.in.tum.de/personen/albers/papers/ipl02.pdf Randomized Splay Trees}
+ * @template K, V
+ */
+export declare class SplayTree<K, V = any> extends Mapping<K, V> {
+    protected root?: Node<K, V>;
+    protected cmp: Comparer;
+    protected randSplay: number;
+    protected count: number;
+    /**
+     * Create a new randomized Splay Tree
+     * @param compareFn
+     * @param p When an element is accessed, with probability `p` splay the tree. With probability `1 - p`, leave the tree as it is.
+     */
+    constructor(compareFn?: any, p?: number);
+    top(): K | undefined;
+    get size(): number;
+    empty(): boolean;
+    get height(): any;
+    /**
+     *  Returns the value for `key` or `undefined` if the key is not found.
+     * @param key The key to find.
+     * @returns {?V} The value for the key or `undefined`.
+     */
+    get(key: K): any;
+    /**
+     * Inserts the `key` and `value` in the tree if the `key` does not exist.
+     * @param {K} key A key which can be any comparable value
+     * @param {V} value A value associated with the key
+     * @returns
+     */
+    set(key: K, value: V): void;
+    /**
+     * Removes a specified key if it exists in the tree. The removed value is returned or `undefined` if not found.
+     * @param {K} key The key to remove.
+     * @returns {V} The removed value associated with `key`.
+     */
+    remove(key: K): V | undefined;
+    /**
+     * Returns the minimum key in the tree or subtree.
+     * @returns The minimum key.
+     */
+    min(root?: Node<K, V> | undefined): K | undefined;
+    /**
+     * Returns the maximum key in the tree or subtree.
+     * @returns The maximum key.
+     */
+    max(root?: Node<K, V> | undefined): K | undefined;
+    /**
+     * Returns the largest key that is less than a given key.
+     * @param key The given key
+     * @returns The largest key found or `undefined`.
+     */
+    lowerBound(key: any): K | Node<K, V> | undefined;
+    /**
+     * This is the simplified top-down splaying method proposed by Sleator and Tarjan in {@link https://doi.org/10.1145%2F3828.3835 Self-Adjusting Binary Search Trees}.
+     * @param key
+     * @see {@link https://doi.org/10.1145%2F3828.3835 Self-Adjusting Binary Search Trees}
+     */
+    splay(key: any): void;
+    add(key: K): void;
+    /**
+     * Returns `true` if the given key is in the tree.
+     * @param {K} key The key to find.
+     * @returns `true` if found.
+     */
+    contains(key: K): boolean;
+    /** Alias of remove but just returns `true` instead of the deleted value. */
+    delete(key: K): boolean;
+    clear(): void;
+    /**
+     * Returns an ordered iterable of all the keys in the tree.
+     * @returns {Iterable<K>} An iterable of keys in-order.
+     */
+    keys(): Iterable<K>;
+    /**
+     * Returns an ordered iterable of all the keys and values in the tree.
+     * @returns {Iterable<[K,V]>} A iterable of `[key, value]` pairs sorted by key.
+     */
+    entries(): Iterable<[K, V]>;
+    /**
+     * Returns an ordered iterable of all the keys and values in the tree.
+     * @returns {Iterable<V>} A iterable of `[key, value]` pairs sorted by key.
+     */
+    values(): Iterable<V>;
+}
+export {};

package/core/collections/SplayTree.js

@@ -0,0 +1,338 @@
+import { compare, eq } from '../operators/index.js';
+import { Mapping } from './abc.js';
+/**
+ * Base SplayTree node class.
+ * @private
+ */
+class Node {
+    key;
+    value;
+    left;
+    right;
+    constructor(key, value) {
+        this.key = key;
+        this.value = value;
+    }
+    get height() {
+        if (this.left && this.right)
+            return 1 + Math.max(this.right.height, this.left.height);
+        if (this.right)
+            return 1 + this.right.height;
+        if (this.left)
+            return 1 + this.left.height;
+        return 0;
+    }
+}
+// In-order traversal of a tree
+function* traverse(node) {
+    while (node) {
+        yield* traverse(node.left);
+        yield node;
+        node = node.right;
+    }
+}
+/**
+ * A splay tree is a *self-balancing binary* search tree with the additional property that recently accessed elements are quick to access again.
+ * Insertion, look-up and removal in O(log n) *amortized* time.
+ * For many patterns of non-random operations splay trees can take better than logarithmic time, without requiring advance knowledge of the pattern.
+ * @see {@link https://en.wikipedia.org/wiki/Splay_tree Splay tree}
+ * @see {@link https://web.archive.org/web/20220930173835/http://www14.in.tum.de/personen/albers/papers/ipl02.pdf Randomized Splay Trees}
+ * @template K, V
+ */
+export class SplayTree extends Mapping {
+    root;
+    cmp;
+    randSplay;
+    count;
+    /**
+     * Create a new randomized Splay Tree
+     * @param compareFn
+     * @param p When an element is accessed, with probability `p` splay the tree. With probability `1 - p`, leave the tree as it is.
+     */
+    constructor(compareFn, p = 0.5) {
+        super();
+        this.cmp = compareFn ?? compare;
+        this.count = 0;
+        this.randSplay = p;
+    }
+    top() {
+        return this.root?.key;
+    }
+    get size() {
+        return this.count;
+    }
+    empty() {
+        return !this.root;
+    }
+    get height() {
+        if (!this.root)
+            return 0;
+        return this.root.height;
+    }
+    /**
+     *  Returns the value for `key` or `undefined` if the key is not found.
+     * @param key The key to find.
+     * @returns {?V} The value for the key or `undefined`.
+     */
+    get(key) {
+        if (!this.root)
+            return;
+        // Note: deterministic splaying (always moves key to front):
+        // this.splay(key)
+        // if (this.cmp(key, this.root.key) === 0) return this.root.value
+        // Randomized Splay Trees https://doi.org/10.1016%2Fs0020-0190%2801%2900230-7
+        // The randomized idea is only moving accessed keys with a certain probability `p`.
+        // Values of `p` closer to 1 tend to perform well.
+        if (Math.random() <= this.randSplay) {
+            this.splay(key);
+            if (this.cmp(key, this.root.key) === 0)
+                return this.root.value;
+            else
+                return undefined;
+        }
+        // Lookup the node down the tree
+        let current = this.root;
+        while (current) {
+            const rank = this.cmp(key, current.key);
+            if (rank === 0)
+                return current.value;
+            if (rank < 0)
+                current = current.left;
+            else
+                current = current.right;
+        }
+    }
+    /**
+     * Inserts the `key` and `value` in the tree if the `key` does not exist.
+     * @param {K} key A key which can be any comparable value
+     * @param {V} value A value associated with the key
+     * @returns
+     */
+    set(key, value) {
+        if (!this.root) {
+            this.root = new Node(key, value);
+            this.count += 1;
+            return;
+        }
+        // Splay on the key to move the last node on the search path for
+        // the key to the root of the tree.
+        this.splay(key);
+        const rank = this.cmp(key, this.root.key);
+        if (rank === 0) {
+            // Update the value
+            this.root.value = value;
+            return;
+        }
+        const node = new Node(key, value);
+        if (rank > 0) {
+            node.left = this.root;
+            node.right = this.root.right;
+            this.root.right = undefined;
+        }
+        else {
+            node.right = this.root;
+            node.left = this.root.left;
+            this.root.left = undefined;
+        }
+        this.root = node;
+        this.count += 1;
+    }
+    /**
+     * Removes a specified key if it exists in the tree. The removed value is returned or `undefined` if not found.
+     * @param {K} key The key to remove.
+     * @returns {V} The removed value associated with `key`.
+     */
+    remove(key) {
+        if (!this.root) {
+            return;
+        }
+        this.splay(key);
+        if (!eq(key, this.root.key)) {
+            return;
+        }
+        const removed = this.root;
+        if (!this.root.left) {
+            this.root = this.root.right;
+        }
+        else {
+            const right = this.root.right;
+            this.root = this.root.left;
+            //
+            // Splay to make sure that the new root has an empty right child.
+            //
+            this.splay(key);
+            //
+            // Insert the original right child as the right child of the new
+            // root.
+            //
+            this.root.right = right;
+        }
+        this.count -= 1;
+        return removed.value;
+    }
+    //
+    //  function find(key)
+    //  @param {number} key Key to find in the tree.
+    //  @return {SplayTree.Node} Node having the specified key.
+    //
+    //
+    /**
+     * Returns the minimum key in the tree or subtree.
+     * @returns The minimum key.
+     */
+    min(root = this.root) {
+        if (!root)
+            return;
+        while (root.left) {
+            root = root.left;
+        }
+        return root.key;
+    }
+    /**
+     * Returns the maximum key in the tree or subtree.
+     * @returns The maximum key.
+     */
+    max(root = this.root) {
+        if (!root)
+            return;
+        while (root.right) {
+            root = root.right;
+        }
+        return root.key;
+    }
+    /**
+     * Returns the largest key that is less than a given key.
+     * @param key The given key
+     * @returns The largest key found or `undefined`.
+     */
+    lowerBound(key) {
+        if (!this.root)
+            return;
+        // Splay on the key to move the node with the given key or the last
+        // node on the search path to the top of the tree.
+        this.splay(key);
+        // Now the result is either the root node or the greatest node in
+        // the left subtree.
+        if (this.cmp(this.root.key, key) < 0) {
+            return this.root;
+        }
+        else if (this.root.left) {
+            return this.max(this.root.left);
+        }
+    }
+    /**
+     * This is the simplified top-down splaying method proposed by Sleator and Tarjan in {@link https://doi.org/10.1145%2F3828.3835 Self-Adjusting Binary Search Trees}.
+     * @param key
+     * @see {@link https://doi.org/10.1145%2F3828.3835 Self-Adjusting Binary Search Trees}
+     */
+    splay(key) {
+        if (!this.root)
+            return;
+        let stub, left, right;
+        // eslint-disable-next-line
+        stub = left = right = new Node(null, null);
+        let root = this.root;
+        while (true) {
+            const rank = this.cmp(key, root.key);
+            if (rank < 0) {
+                if (!root.left) {
+                    break;
+                }
+                if (this.cmp(key, root.left.key) < 0) {
+                    // Rotate right.
+                    const tmp = root.left;
+                    root.left = tmp.right;
+                    tmp.right = root;
+                    root = tmp;
+                    if (!root.left) {
+                        break;
+                    }
+                }
+                // Link right.
+                right.left = root;
+                right = root;
+                root = root.left;
+            }
+            else if (rank > 0) {
+                if (!root.right) {
+                    break;
+                }
+                if (this.cmp(key, root.right.key) > 0) {
+                    // Rotate left.
+                    const tmp = root.right;
+                    root.right = tmp.left;
+                    tmp.left = root;
+                    root = tmp;
+                    if (!root.right) {
+                        break;
+                    }
+                }
+                // Link left.
+                left.right = root;
+                left = root;
+                root = root.right;
+            }
+            else {
+                break;
+            }
+        }
+        // Assemble.
+        left.right = root.left;
+        right.left = root.right;
+        root.left = stub.right;
+        root.right = stub.left;
+        this.root = root;
+    }
+    add(key) {
+        return this.set(key, null);
+    }
+    /**
+     * Returns `true` if the given key is in the tree.
+     * @param {K} key The key to find.
+     * @returns `true` if found.
+     */
+    contains(key) {
+        return this.get(key) !== undefined;
+    }
+    /** Alias of remove but just returns `true` instead of the deleted value. */
+    delete(key) {
+        // since remove throws, this will throw too
+        this.remove(key);
+        return true;
+    }
+    clear() {
+        if (!this.root)
+            return;
+        this.root.left = undefined;
+        this.root.right = undefined;
+        this.root = undefined;
+        this.count = 0;
+    }
+    /**
+     * Returns an ordered iterable of all the keys in the tree.
+     * @returns {Iterable<K>} An iterable of keys in-order.
+     */
+    *keys() {
+        for (const node of traverse(this.root)) {
+            yield node.key;
+        }
+    }
+    /**
+     * Returns an ordered iterable of all the keys and values in the tree.
+     * @returns {Iterable<[K,V]>} A iterable of `[key, value]` pairs sorted by key.
+     */
+    *entries() {
+        for (const node of traverse(this.root)) {
+            yield [node.key, node.value];
+        }
+    }
+    /**
+     * Returns an ordered iterable of all the keys and values in the tree.
+     * @returns {Iterable<V>} A iterable of `[key, value]` pairs sorted by key.
+     */
+    *values() {
+        for (const node of traverse(this.root)) {
+            yield node.value;
+        }
+    }
+}