data-structure-typed 2.4.5 → 2.5.0

package/src/data-structures/binary-tree/tree-multi-set.ts

@@ -84,6 +84,15 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Number of distinct keys.
    * @remarks Time O(1), Space O(1)
+   
+   
+   
+    * @example
+ * // Unique key count
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 3);
+ *       ms.add(2, 2);
+ *       console.log(ms.distinctSize); // 2;
    */
   get distinctSize(): number {
     return this.#core.size;
@@ -92,6 +101,52 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Whether the multiset is empty.
    * @remarks Time O(1), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Check empty
+ *  console.log(new TreeMultiSet().isEmpty()); // true;
    */
   isEmpty(): boolean {
     return this.size === 0;
@@ -100,6 +155,58 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Whether the multiset contains the given key.
    * @remarks Time O(log n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Check existence
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1);
+ *       console.log(ms.has(1)); // true;
+ *       console.log(ms.has(2)); // false;
    */
   has(key: K): boolean {
     this._validateKey(key);
@@ -109,6 +216,14 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Returns the count of occurrences for the given key.
    * @remarks Time O(log n), Space O(1)
+   
+   
+   
+    * @example
+ * // Get occurrence count
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 5);
+ *       console.log(ms.count(1)); // 5;
    */
   count(key: K): number {
     this._validateKey(key);
@@ -119,6 +234,51 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    * Add `n` occurrences of `key`.
    * @returns True if the multiset changed.
    * @remarks Time O(log n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Add elements
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1);
+ *       ms.add(1);
+ *       ms.add(2);
+ *       console.log(ms.count(1)); // 2;
+ *       console.log(ms.size); // 3;
    */
   add(key: K, n = 1): boolean {
     this._validateKey(key);
@@ -136,6 +296,14 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    * Set count for `key` to exactly `n`.
    * @returns True if changed.
    * @remarks Time O(log n), Space O(1)
+   
+   
+   
+    * @example
+ * // Set occurrence count
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.setCount(1, 3);
+ *       console.log(ms.count(1)); // 3;
    */
   setCount(key: K, n: number): boolean {
     this._validateKey(key);
@@ -158,6 +326,58 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    * Delete `n` occurrences of `key` (default 1).
    * @returns True if any occurrence was removed.
    * @remarks Time O(log n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove one occurrence
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 3);
+ *       ms.delete(1);
+ *       console.log(ms.count(1)); // 2;
    */
   delete(key: K, n = 1): boolean {
     this._validateKey(key);
@@ -181,6 +401,15 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    * Delete all occurrences of the given key.
    * @returns True if any occurrence was removed.
    * @remarks Time O(log n), Space O(1)
+   
+   
+   
+    * @example
+ * // Remove all occurrences
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 3);
+ *       ms.deleteAll(1);
+ *       console.log(ms.has(1)); // false;
    */
   deleteAll(key: K): boolean {
     this._validateKey(key);
@@ -194,6 +423,15 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Iterates over distinct keys (each key yielded once).
    * @remarks Time O(n), Space O(1)
+   
+   
+   
+    * @example
+ * // Iterate unique keys
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       ms.add(2);
+ *       console.log([...ms.keysDistinct()]); // [1, 2];
    */
   *keysDistinct(): IterableIterator<K> {
     yield* this.#core.keys();
@@ -202,6 +440,54 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Iterates over entries as [key, count] pairs.
    * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Iterate entries
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       console.log([...ms.entries()].length); // > 0;
    */
   *entries(): IterableIterator<[K, number]> {
     for (const [k, v] of this.#core) {
@@ -222,6 +508,55 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Returns an array with all elements (expanded).
    * @remarks Time O(size), Space O(size)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // All elements (with duplicates)
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       ms.add(2);
+ *       console.log(ms.toArray()); // [1, 1, 2];
    */
   toArray(): K[] {
     return [...this];
@@ -230,6 +565,15 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Returns an array with distinct keys only.
    * @remarks Time O(n), Space O(n)
+   
+   
+   
+    * @example
+ * // Unique keys only
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 3);
+ *       ms.add(2);
+ *       console.log(ms.toDistinctArray()); // [1, 2];
    */
   toDistinctArray(): K[] {
     return [...this.keysDistinct()];
@@ -238,6 +582,15 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Returns an array of [key, count] entries.
    * @remarks Time O(n), Space O(n)
+   
+   
+   
+    * @example
+ * // Key-count pairs
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       ms.add(3);
+ *       console.log(ms.toEntries()); // [[1, 2], [3, 1]];
    */
   toEntries(): Array<[K, number]> {
     return [...this.entries()];
@@ -256,10 +609,56 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Remove all elements from the multiset.
    * @remarks Time O(1), Space O(1)
-   * @example
-   * const ms = new TreeMultiSet([1, 2, 2, 3]);
-   * ms.clear();
-   * ms.size;  // 0
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove all
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1);
+ *       ms.clear();
+ *       console.log(ms.isEmpty()); // true;
    */
   clear(): void {
     this.#core.clear();
@@ -271,9 +670,16 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Returns the smallest key, or undefined if empty.
    * @remarks Time O(log n), Space O(1)
-   * @example
-   * const ms = new TreeMultiSet([3, 1, 4]);
-   * ms.first();  // 1
+  
+   
+   
+   
+    * @example
+ * // Smallest element
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(3);
+ *       ms.add(1);
+ *       console.log(ms.first()); // 1;
    */
   first(): K | undefined {
     return this.#core.getLeftMost();
@@ -282,9 +688,16 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Returns the largest key, or undefined if empty.
    * @remarks Time O(log n), Space O(1)
-   * @example
-   * const ms = new TreeMultiSet([3, 1, 4]);
-   * ms.last();  // 4
+  
+   
+   
+   
+    * @example
+ * // Largest element
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1);
+ *       ms.add(3);
+ *       console.log(ms.last()); // 3;
    */
   last(): K | undefined {
     return this.#core.getRightMost();
@@ -293,10 +706,17 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Removes all occurrences of the smallest key and returns it.
    * @remarks Time O(log n), Space O(1)
-   * @example
-   * const ms = new TreeMultiSet([1, 1, 2, 3]);
-   * ms.pollFirst();  // 1
-   * ms.has(1);       // false
+  
+   
+   
+   
+    * @example
+ * // Remove and return smallest
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(2);
+ *       ms.add(1);
+ *       console.log(ms.pollFirst()); // 1;
+ *       console.log(ms.has(1)); // false;
    */
   pollFirst(): K | undefined {
     const key = this.first();
@@ -308,10 +728,16 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Removes all occurrences of the largest key and returns it.
    * @remarks Time O(log n), Space O(1)
-   * @example
-   * const ms = new TreeMultiSet([1, 2, 3, 3]);
-   * ms.pollLast();  // 3
-   * ms.has(3);      // false
+  
+   
+   
+   
+    * @example
+ * // Remove and return largest
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1);
+ *       ms.add(3);
+ *       console.log(ms.pollLast()); // 3;
    */
   pollLast(): K | undefined {
     const key = this.last();
@@ -323,10 +749,47 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Returns the smallest key >= given key, or undefined.
    * @remarks Time O(log n), Space O(1)
-   * @example
-   * const ms = new TreeMultiSet([10, 20, 30]);
-   * ms.ceiling(15);  // 20
-   * ms.ceiling(20);  // 20
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Least key ≥ target
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(10);
+ *       ms.add(20);
+ *       ms.add(30);
+ *       console.log(ms.ceiling(15)); // 20;
    */
   ceiling(key: K): K | undefined {
     this._validateKey(key);
@@ -336,10 +799,47 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Returns the largest key <= given key, or undefined.
    * @remarks Time O(log n), Space O(1)
-   * @example
-   * const ms = new TreeMultiSet([10, 20, 30]);
-   * ms.floor(25);  // 20
-   * ms.floor(20);  // 20
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Greatest key ≤ target
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(10);
+ *       ms.add(20);
+ *       ms.add(30);
+ *       console.log(ms.floor(25)); // 20;
    */
   floor(key: K): K | undefined {
     this._validateKey(key);
@@ -349,10 +849,46 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Returns the smallest key > given key, or undefined.
    * @remarks Time O(log n), Space O(1)
-   * @example
-   * const ms = new TreeMultiSet([10, 20, 30]);
-   * ms.higher(10);  // 20
-   * ms.higher(15);  // 20
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Least key > target
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(10);
+ *       ms.add(20);
+ *       console.log(ms.higher(10)); // 20;
    */
   higher(key: K): K | undefined {
     this._validateKey(key);
@@ -362,10 +898,46 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Returns the largest key < given key, or undefined.
    * @remarks Time O(log n), Space O(1)
-   * @example
-   * const ms = new TreeMultiSet([10, 20, 30]);
-   * ms.lower(20);  // 10
-   * ms.lower(15);  // 10
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Greatest key < target
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(10);
+ *       ms.add(20);
+ *       console.log(ms.lower(20)); // 10;
    */
   lower(key: K): K | undefined {
     this._validateKey(key);
@@ -377,10 +949,58 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Iterates over distinct keys with their counts.
    * @remarks Time O(n), Space O(1)
-   * @example
-   * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
-   * ms.forEach((key, count) => console.log(`${key}: ${count}`));
-   * // 1: 2, 2: 1, 3: 3
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Iterate
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       ms.add(2);
+ *       const pairs: [number, number][] = [];
+ *       ms.forEach((k, c) => pairs.push([k, c]));
+ *       console.log(pairs); // [[1, 2], [2, 1]];
    */
   forEach(callback: (key: K, count: number) => void): void {
     for (const [k, c] of this.entries()) {
@@ -391,10 +1011,58 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Creates a new TreeMultiSet with entries that match the predicate.
    * @remarks Time O(n log n), Space O(n)
-   * @example
-   * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
-   * const filtered = ms.filter((key, count) => count >= 2);
-   * // TreeMultiSet { 1: 2, 3: 3 }
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Filter
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 3);
+ *       ms.add(2, 1);
+ *       ms.add(3, 2);
+ *       const filtered = ms.filter((k, c) => c > 1);
+ *       console.log([...filtered.keysDistinct()]); // [1, 3];
    */
   filter(predicate: (key: K, count: number) => boolean): TreeMultiSet<K> {
     const result = new TreeMultiSet<K>([], {
@@ -412,9 +1080,57 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Reduces the multiset to a single value.
    * @remarks Time O(n), Space O(1)
-   * @example
-   * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
-   * const total = ms.reduce((acc, key, count) => acc + count, 0);  // 6
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Aggregate
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       ms.add(2, 3);
+ *       const sum = ms.reduce((acc, k, c) => acc + k * c, 0);
+ *       console.log(sum); // 8;
    */
   reduce<U>(callback: (accumulator: U, key: K, count: number) => U, initialValue: U): U {
     let acc = initialValue;
@@ -428,15 +1144,57 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    * Maps keys and counts to a new TreeMultiSet.
    * When multiple keys map to the same new key, counts are merged (added).
    * @remarks Time O(n log n), Space O(n)
-   * @example
-   * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
-   * const mapped = ms.map((key, count) => [key * 10, count]);
-   * // TreeMultiSet { 10: 2, 20: 1, 30: 3 }
-   * @example
-   * // Collision: counts merge
-   * const ms = new TreeMultiSet([1, 2, 3]);
-   * const merged = ms.map((key, count) => [key % 2, count]);
-   * // { 0: 1, 1: 2 }  (1 and 3 both map to 1, counts add)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Transform
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       ms.add(2, 3);
+ *       const doubled = ms.map((k, c) => [k * 10, c] as [number, number]);
+ *       console.log([...doubled.keysDistinct()]); // [10, 20];
    */
   map<K2>(
     mapper: (key: K, count: number) => [K2, number],
@@ -456,11 +1214,57 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Creates an independent copy of this multiset.
    * @remarks Time O(n log n), Space O(n)
-   * @example
-   * const ms = new TreeMultiSet([1, 1, 2]);
-   * const copy = ms.clone();
-   * copy.add(3);
-   * ms.has(3);  // false (original unchanged)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Deep clone
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 3);
+ *       const copy = ms.clone();
+ *       copy.deleteAll(1);
+ *       console.log(ms.has(1)); // true;
    */
   clone(): TreeMultiSet<K> {
     const result = new TreeMultiSet<K>([], {
@@ -478,9 +1282,48 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Returns keys within the given range.
    * @remarks Time O(log n + k), Space O(k) where k is result size
-   * @example
-   * const ms = new TreeMultiSet([10, 20, 30, 40, 50]);
-   * ms.rangeSearch([15, 45]);  // [20, 30, 40]
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Find in range
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(10);
+ *       ms.add(20);
+ *       ms.add(30);
+ *       const result = ms.rangeSearch([15, 25]);
+ *       console.log(result.length); // 1;
    */
   rangeSearch<C extends (key: K) => any>(
     range: [K, K],
@@ -493,9 +1336,55 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
   /**
    * Prints the internal tree structure (for debugging).
    * @remarks Time O(n), Space O(n)
-   * @example
-   * const ms = new TreeMultiSet([1, 2, 3]);
-   * ms.print();
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Display
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1);
+ *       expect(() => ms.print()).not.toThrow();
    */
   print(): void {
     this.#core.print();