binary-tree-typed 2.4.4 → 2.5.0

package/dist/types/data-structures/binary-tree/tree-multi-set.d.ts

@@ -43,55 +43,311 @@ export declare 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;
     /**
      * Whether the multiset is empty.
      * @remarks Time O(1), Space O(1)
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Check empty
+   *  console.log(new TreeMultiSet().isEmpty()); // true;
      */
     isEmpty(): boolean;
     /**
      * 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;
     /**
      * 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;
     /**
      * 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?: number): boolean;
     /**
      * 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;
     /**
      * 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?: number): boolean;
     /**
      * 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;
     /**
      * 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>;
     /**
      * 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]>;
     /**
@@ -102,16 +358,76 @@ export declare 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[];
     /**
      * 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[];
     /**
      * 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]>;
     /**
@@ -122,121 +438,481 @@ export declare 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;
     /**
      * 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;
     /**
      * 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;
     /**
      * 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;
     /**
      * 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;
     /**
      * 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;
     /**
      * 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;
     /**
      * 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;
     /**
      * 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;
     /**
      * 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;
     /**
      * 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>;
     /**
      * 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;
     /**
      * 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], options?: {
         comparator?: Comparator<K2>;
@@ -244,27 +920,144 @@ export declare 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>;
     /**
      * 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], callback?: C): (C extends undefined ? K : ReturnType<C>)[];
     /**
      * 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;
 }