dubc-ds-tmap 1.0.0 → 1.0.1

package/README.md

@@ -1,3 +1,261 @@
 # dubc-ds-tmap
 
-Observable sorted map based on a weighted binary search tree.
+A map (dictionary) of key/value pairs that is sorted using a weighted
+binary search tree. 
+
+Note that this data structure maps _arbitrary_ keys to _arbitrary_
+values. When doing front-end development, that's usually not what
+you actually need. Consider using `dubc-ds-tindex` instead, which
+provides a dictionary where the keys are a function of the values.
+
+## Constructor
+
+```TypeScript
+constructor(conf:Conf<K,V>, pairs:Pairs<K,V>)
+```
+
+To construct a `TMap`, you need a configuration object that supplies
+three things:
+
+1. A `compare` function that determines how to sort the keys in the map.
+2. A `unique` flag that determines whether the map can contain duplicate keys.
+3. A `valueEq` function that determines how values should be compared.
+
+You also can supply initial key/value pairs to populate the map. The
+pairs can be specified in three ways:
+
+1. You can specify an iterable of objects with `key` and `value` fields;
+2. Or an iterable of key/value tuples, where the first part of the tuple
+   is the key and the second part of the tuplie is the value;
+3. Or, if the keys are strings, you can use a plain JavaScript object.
+
+If you want unique keys and can use `Object.is` for your `valueEq` function,
+you can use the static `of` method to construct a `TMap` with variadic 
+key/value pairs.
+
+Example:
+
+```TypeScript
+import { Conf, TMap } from "dubc-ds-tmap"
+
+const compare = (a:string, b:string) => a.localeCompare(b)
+
+const conf:Conf<string,number> = {
+  compare, unique:false, valueEq:Object.is,
+}
+
+// These five statements all do the same thing.
+const map1 = new TMap(conf, [{key:"1", value:1}, {key:"2", value:2}])
+const map2 = new TMap(conf, [["1", 1], ["2", 2]])
+const map3 = new TMap(conf, {"1":1, "2":2})
+const map4 = TMap.of(compare, {key:"1", value:1}, {key:"2", value:2})
+const map5 = TMap.of(compare, ["1", 1], ["2", 2])
+```
+
+## Properties
+
+### `.compare` O(1)
+
+Returns the current function used to compare keys. This property is
+mutable: If you change it, the map will re-sort (and fire a notification
+to any listeners that the map has changed.)
+
+### `.first` O(log n)
+
+Returns the first key/value pair in the map, or `undefined` if the map
+is empty.
+
+### `.i` O(1)
+
+Returns an iterator over the key/value pairs in the map. Each value
+returned by the iterator will be an immutable object in the form `{key:k, value:v}`. (This property is inherited from `Base`.)
+
+### `.last` O(log n)
+
+Returns the last key/value pair in the map, or `undefined` if the map
+is empty.
+
+### `.only` O(1)
+
+Returns the only key/value pair in the map. If the map doesn't have
+exactly one element, throws an `Error`.
+
+### `.size` O(1)
+
+Returns the number of key/value pairs in the map.
+
+## Methods
+
+### `.after(k:K)` O(log n)
+
+Returns the key/value pair whose key is strictly greater than the provided
+key, or `undefined` if no such pair exists in the map.
+
+### `.at(index:number)` O(log n)
+
+Returns the key/value pair at the specified index in the sort order.
+Throws a `TypeError` if the index is out of bounds.
+
+### `.before(k:K)` O(log n)
+
+Returns the key/value pair whose key is strictly less than the provided
+key, or `undefined` if no such pair exists in the map.
+
+### `.delete(k:K)` O(log n)
+
+Removes the given key from the map. Returns the value that was mapped
+to the key, or `undefined` if the key was not in the map.
+
+### `.deleteAll(i:Iterable<K>)` O(k * log n)
+
+Removes every key provided by the given iterable from the map.
+Returns the number of pairs that were deleted.
+
+### `.drop(f:(pair:Pair<K,V>)=>boolean)` O(n)
+
+Safely removes all key/value pairs that match the provided predicate
+function from the map. Use this instead of calling `delete` from within
+an iteration. Returns the number of pairs that were dropped.
+
+### `.from(k:K)` O(log n)
+
+Returns the key/value pair whose key is greater than or equal to the provided
+key, or `undefined` if no such pair exists in the map.
+
+### `.get(k:K)` O(log n)
+
+Returns the value for the given key, or `undefined` if no such key exists
+in the map.
+
+### `.has(k:K)` O(log n)
+
+Returns true if the map contains the given key, or false if it doesn't.
+
+### `.hasAll(i:Iterable<K>)` O(k * log n)
+
+Returns true if the map contains every key produced by the given iterable,
+or false if it doesn't.
+
+### `.hear(f:(event:DSEvent<Pair<K,V>>))` O(1)
+
+Adds a listener to the map. Any time the map changes (and _only_ when
+the map actually changes), the listener function will be called.
+
+Returns a number that can be sent to `unhear` to stop receiving events.
+
+### `.keys()` O(1)
+
+Returns an iterable iterator over the keys in the map.
+
+### `.range(start:K, end:K, include?:Include)` O(1)
+
+Returns an iterable iterator over a range of keys in the map. The 
+iterator will produce key/value pairs.
+
+The optional third parameter specifies whether the range is inclusive
+or exclusive, and must be one of the following four constants:
+
+1. `IN_EX`: Start is inclusive, end is exclusive. This is the default.
+2. `IN_IN`: Both start and end are inclusive.
+3. `EX_IN`: Start is exclusive, end is inclusive.
+4. `EX_EX`: Both start and end are exclusive.
+
+### `.rank(k:K)` O(log n)
+
+Returns the index of the given key in the map's sort order, or
+`undefined` if the key is not in the map.
+
+### `.replace(pairs:Pairs<K,V>)` O(k * log n)
+
+Replaces the content of this map with new key/value pairs.
+
+The provided pairs can be in one of the three forms accepted by
+`TMap`'s constructor (objects with key and value fields, tuples of
+keys and values, or, for string keys, a JavaScript object.)
+
+### `.reversed()` O(1)
+
+Returns an iterable iterator over the pairs in the map, in reverse
+sort order.
+
+### `.set(key:K, value:V)` O(log n)
+
+Adds a pair to the map.
+
+If the map uses unique keys and the key already exists in the map,
+then `set` will replace the value for that key and return the old key.
+
+Otherwise, `set` will add a new pair to the map and return `undefined`.
+
+### `.setAll(pairs:Pairs<K,V>)` O(k * log n)
+
+Adds many pairs to the map. Returns the number of pairs that were newly
+added. (The number returned does not include any keys that were 
+already in a unique map.)
+
+The provided pairs can be in one of the three forms accepted by
+`TMap`'s constructor (objects with key and value fields, tuples of
+keys and values, or, for string keys, a JavaScript object.)
+
+### `.unhear(n:number)` O(1)
+
+Removes the listener registered with the specified number.
+
+### `.values()` O(1)
+
+Returns an iterable iterator over the values in the map.
+
+## Operations by Kind
+
+### Listeners
+
+* `hear(eventHandler)` to get events when the map changes
+* `unhear(n)` to stop listening for changes
+
+### Iterators
+
+* `TMap` itself is an iterable, so you can use it directly in `for...of`
+* `i` to get an iterator 
+* `keys()` if you just want the keys
+* `range(start,end,include)` for partial iteration
+* `reversed()` to iterate backwards
+* `values()` if you just want the values
+
+### Keys
+
+* `get(key)` to get the value for a key
+* `has(key)` to determine if the key exists
+* `hasAll(iterable)` to determin if all the keys exist
+* `only` to get the only pair
+
+### Ordering
+
+* `get compare` for the sort function
+
+* `first` to get the first pair
+* `last` to get the last pair
+
+* `after(key)` to get the pair > key
+* `before(key)` to get the pair < key
+* `from(key)` to get the pair >= key
+* `to(key)` to get the pair <= key
+
+### Indices
+
+* `at(index)` to get the key at an index
+* `rank(key)` to get the index of a key
+* `size` to get the number of pairs
+
+### Adding/Changing
+
+* `set compare` to re-sort the map
+* `set(key,value)` add a pair to the map
+* `setAll(pairs)` add many pairs to the map
+* `replace(pairs)` clear the map then add many pairs
+
+### Deleting
+
+* `clear()` delete everything
+* `delete(key)` delete a specific key
+* `deleteAll(iterable)` delete many keys
+* `drop(predicate)` delete pairs that match a predicate

package/dist/index.d.ts

@@ -21,7 +21,7 @@ export declare const EX_EX: {
     end: boolean;
 };
 type N<K extends {}, V> = Node<K, V> | undefined;
-declare class Node<K extends {}, V> {
+declare class Node<K extends {}, V> implements Pair<K, V> {
     readonly key: K;
     value: V;
     weight: number;
@@ -51,20 +51,16 @@ export declare class TMap<K extends {}, V> extends Base<Pair<K, V>> {
     get size(): number;
     clear(): void;
     replace(i: Pairs<K, V>): void;
-    drop(f: (pair: Pair<K, V>) => boolean): void;
+    drop(f: (pair: Pair<K, V>) => boolean): number;
     get compare(): (a: K, b: K) => number;
     set compare(cmp: (a: K, b: K) => number);
-    get keyEq(): (a: K, b: K) => boolean;
-    get unique(): boolean;
     at(i: number): Pair<K, V>;
     get only(): Pair<K, V>;
     get first(): Pair<K, V> | undefined;
     get last(): Pair<K, V> | undefined;
-    [Symbol.iterator](): Generator<Node<K, V>, void, unknown>;
-    private keys2;
-    get keys(): Iterable<K>;
-    private values2;
-    get values(): Iterable<V>;
+    [Symbol.iterator](): Generator<Pair<K, V>>;
+    keys(): Generator<K, void, unknown>;
+    values(): Generator<V, void, unknown>;
     reversed(): Generator<Pair<K, V>, void, unknown>;
     range(startKey: K, endKey: K, inc?: Include): Generator<Pair<K, V>, void, unknown>;
     private find;
@@ -74,6 +70,7 @@ export declare class TMap<K extends {}, V> extends Base<Pair<K, V>> {
     to(key: K): Pair<K, V> | undefined;
     after(key: K): Pair<K, V> | undefined;
     before(key: K): Pair<K, V> | undefined;
+    hasAll(keys: Iterable<K>): boolean;
     rank(key: K): number | undefined;
     protected rawPut(key: K, value: V): {
         node: Node<K, V>;
@@ -82,7 +79,9 @@ export declare class TMap<K extends {}, V> extends Base<Pair<K, V>> {
     set(key: K, value: V): V | undefined;
     setAll(entries: Pairs<K, V>): number;
     delete(key: K): V | undefined;
-    private remove;
+    private delete2;
+    deleteAll(i: Iterable<K>): number;
+    private rawDelete;
     private weigh;
 }
 export {};

package/dist/index.js

@@ -104,13 +104,7 @@ export class TMap extends Base {
         return new TMap(pairs, conf);
     }
     toEmpty() {
-        const conf2 = {
-            unique: this.conf.unique,
-            valueEq: this.conf.valueEq,
-            compare: this._compare,
-        };
-        const r = new TMap(this, conf2);
-        return r;
+        return new TMap([], this.conf);
     }
     get size() { var _a, _b; return (_b = (_a = this.root) === null || _a === void 0 ? void 0 : _a.weight) !== null && _b !== void 0 ? _b : 0; }
     clear() {
@@ -135,16 +129,19 @@ export class TMap extends Base {
     drop(f) {
         let n = this.first;
         let at = 0;
+        let c = 0;
         while (n !== undefined) {
             const x = n;
             n = n.next();
             if (f(x)) {
-                this.remove(x);
+                this.rawDelete(x);
                 this.fire({ deleted: { items: [x], at: at } });
+                c++;
             }
             else
                 at++;
         }
+        return c;
     }
     get compare() { return this._compare; }
     set compare(cmp) {
@@ -159,13 +156,12 @@ export class TMap extends Base {
         }
         this.fire({ cleared: this.size, added: { items: this, at: 0 } });
     }
-    get keyEq() { return (a, b) => this._compare(a, b) === 0; }
-    get unique() { return this.conf.unique; }
     at(i) {
         var _a;
         let node = this.root;
         let weight = this.size;
-        // if (i < 0) i += weight // TODO
+        if (!Number.isSafeInteger(i))
+            throw new TypeError("index must be an integer");
         if (i < 0 || i >= weight)
             throw new TypeError("bounds");
         while (true) {
@@ -213,20 +209,14 @@ export class TMap extends Base {
             n = n.next();
         }
     }
-    *keys2() {
+    *keys() {
         for (const x of this)
             yield x.key;
     }
-    get keys() {
-        return this.keys2();
-    }
-    *values2() {
+    *values() {
         for (const x of this)
             yield x.value;
     }
-    get values() {
-        return this.values2();
-    }
     *reversed() {
         let n = this.last;
         while (n) {
@@ -249,7 +239,7 @@ export class TMap extends Base {
     find(key, op = EQ) {
         let node = this.root;
         let ret;
-        const unique = this.unique;
+        const unique = this.conf.unique;
         const cmp = this.compare;
         while (node) {
             const c = cmp(node.key, key);
@@ -281,13 +271,19 @@ export class TMap extends Base {
     to(key) { return this.find(key, LE); }
     after(key) { return this.find(key, GT); }
     before(key) { return this.find(key, LT); }
+    hasAll(keys) {
+        for (const x of keys)
+            if (!this.has(x))
+                return false;
+        return true;
+    }
     rank(key) {
         var _a;
         return (_a = this.find(key, EQ)) === null || _a === void 0 ? void 0 : _a.index();
     }
     rawPut(key, value) {
         let previous = undefined, node = this.root;
-        let unique = this.unique ? 0 : undefined;
+        let unique = this.conf.unique ? 0 : undefined;
         let c = 0, cmp = this.compare;
         while (node) {
             c = cmp(node.key, key);
@@ -347,12 +343,26 @@ export class TMap extends Base {
         const node = this.find(key);
         if (node === undefined)
             return undefined;
+        return this.delete2(node);
+    }
+    delete2(node) {
         const at = node.index();
-        this.remove(node);
+        this.rawDelete(node);
         this.fire({ deleted: { items: [node], at } });
         return node.value;
     }
-    remove(node) {
+    deleteAll(i) {
+        let c = 0;
+        for (const x of i) {
+            const node = this.find(x);
+            if (node !== undefined) {
+                c++;
+                this.delete2(node);
+            }
+        }
+        return c;
+    }
+    rawDelete(node) {
         const p = node.parent;
         let left = node.left, right = node.right;
         let bal;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dubc-ds-tmap",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Observable map based on a weighted binary search tree.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,7 +27,7 @@
   "homepage": "https://github.com/p-jack/dubc#readme",
   "dependencies": {
     "dubc-ds-base": "^1.0.2",
-    "dubc-ds-pairs": "^1.0.0"
+    "dubc-ds-pairs": "^1.0.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^3.2.4",