stack-typed 1.48.0 → 1.48.2

package/src/data-structures/base/iterable-base.ts

@@ -0,0 +1,329 @@
+import { ElementCallback, PairCallback, ReduceElementCallback, ReducePairCallback } from "../../types";
+
+export abstract class IterablePairBase<K = any, V = any> {
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The function is an implementation of the Symbol.iterator method that returns an iterable iterator.
+   * @param {any[]} args - The `args` parameter in the code snippet represents a rest parameter. It
+   * allows the function to accept any number of arguments as an array. In this case, the `args`
+   * parameter is used to pass any additional arguments to the `_getIterator` method.
+   */
+  * [Symbol.iterator](...args: any[]): IterableIterator<[K, V]> {
+    yield* this._getIterator(...args);
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The function returns an iterator that yields key-value pairs from the object, where the value can
+   * be undefined.
+   */
+  * entries(): IterableIterator<[K, V | undefined]> {
+    for (const item of this) {
+      yield item;
+    }
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The function returns an iterator that yields the keys of a data structure.
+   */
+  * keys(): IterableIterator<K> {
+    for (const item of this) {
+      yield item[0];
+    }
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The function returns an iterator that yields the values of a collection.
+   */
+  * values(): IterableIterator<V> {
+    for (const item of this) {
+      yield item[1];
+    }
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `every` function checks if every element in a collection satisfies a given condition.
+   * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
+   * `value`, `key`, and `index`. It should return a boolean value indicating whether the condition is
+   * met for the current element in the iteration.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `predicate` function. If `thisArg` is provided, it will be
+   * passed as the first argument to the `predicate` function. If `thisArg` is not provided
+   * @returns The `every` method is returning a boolean value. It returns `true` if every element in
+   * the collection satisfies the provided predicate function, and `false` otherwise.
+   */
+  every(predicate: PairCallback<K, V, boolean>, thisArg?: any): boolean {
+    let index = 0;
+    for (const item of this) {
+      if (!predicate.call(thisArg, item[1], item[0], index++, this)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The "some" function iterates over a collection and returns true if at least one element satisfies
+   * a given predicate.
+   * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
+   * `value`, `key`, and `index`. It should return a boolean value indicating whether the condition is
+   * met for the current element in the iteration.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as the `this` value when executing the `predicate` function. If `thisArg` is provided,
+   * it will be passed as the first argument to the `predicate` function. If `thisArg` is
+   * @returns a boolean value. It returns true if the predicate function returns true for any pair in
+   * the collection, and false otherwise.
+   */
+  some(predicate: PairCallback<K, V, boolean>, thisArg?: any): boolean {
+    let index = 0;
+    for (const item of this) {
+      if (predicate.call(thisArg, item[1], item[0], index++, this)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `forEach` function iterates over each key-value pair in a collection and executes a callback
+   * function for each pair.
+   * @param callbackfn - The callback function that will be called for each element in the collection.
+   * It takes four parameters: the value of the current element, the key of the current element, the
+   * index of the current element, and the collection itself.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that allows you to
+   * specify the value of `this` within the callback function. If `thisArg` is provided, it will be
+   * used as the `this` value when calling the callback function. If `thisArg` is not provided, `
+   */
+  forEach(callbackfn: PairCallback<K, V, void>, thisArg?: any): void {
+    let index = 0;
+    for (const item of this) {
+      const [key, value] = item;
+      callbackfn.call(thisArg, value, key, index++, this)
+    }
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `reduce` function iterates over key-value pairs and applies a callback function to each pair,
+   * accumulating a single value.
+   * @param callbackfn - The callback function that will be called for each element in the collection.
+   * It takes four arguments: the current accumulator value, the current value of the element, the key
+   * of the element, and the index of the element in the collection. It should return the updated
+   * accumulator value.
+   * @param {U} initialValue - The `initialValue` parameter is the initial value of the accumulator. It
+   * is the value that will be used as the first argument to the `callbackfn` function when reducing
+   * the elements of the collection.
+   * @returns The `reduce` method is returning the final value of the accumulator after iterating over
+   * all the elements in the collection.
+   */
+  reduce<U>(callbackfn: ReducePairCallback<K, V, U>, initialValue: U): U {
+    let accumulator = initialValue;
+    let index = 0;
+    for (const item of this) {
+      const [key, value] = item;
+      accumulator = callbackfn(accumulator, value, key, index++, this)
+    }
+    return accumulator;
+  }
+
+  protected abstract _getIterator(...args: any[]): IterableIterator<[K, V]>;
+}
+
+export abstract class IterableElementBase<V> {
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The function is an implementation of the Symbol.iterator method that returns an IterableIterator.
+   * @param {any[]} args - The `args` parameter in the code snippet represents a rest parameter. It
+   * allows the function to accept any number of arguments as an array. In this case, the `args`
+   * parameter is used to pass any number of arguments to the `_getIterator` method.
+   */
+  * [Symbol.iterator](...args: any[]): IterableIterator<V> {
+    yield* this._getIterator(...args);
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The function returns an iterator that yields all the values in the object.
+   */
+  * values(): IterableIterator<V> {
+    for (const item of this) {
+      yield item;
+    }
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `every` function checks if every element in the array satisfies a given predicate.
+   * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
+   * the current element being processed, its index, and the array it belongs to. It should return a
+   * boolean value indicating whether the element satisfies a certain condition or not.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `predicate` function. If `thisArg` is provided, it will be
+   * passed as the `this` value to the `predicate` function. If `thisArg` is
+   * @returns The `every` method is returning a boolean value. It returns `true` if every element in
+   * the array satisfies the provided predicate function, and `false` otherwise.
+   */
+  every(predicate: ElementCallback<V, boolean>, thisArg?: any): boolean {
+    let index = 0;
+    for (const item of this) {
+      if (!predicate.call(thisArg, item as V, index++, this)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The "some" function checks if at least one element in a collection satisfies a given predicate.
+   * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
+   * `value`, `index`, and `array`. It should return a boolean value indicating whether the current
+   * element satisfies the condition.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as the `this` value when executing the `predicate` function. If `thisArg` is provided,
+   * it will be passed as the `this` value to the `predicate` function. If `thisArg
+   * @returns a boolean value. It returns true if the predicate function returns true for any element
+   * in the collection, and false otherwise.
+   */
+  some(predicate: ElementCallback<V, boolean>, thisArg?: any): boolean {
+    let index = 0;
+    for (const item of this) {
+      if (predicate.call(thisArg, item as V, index++, this)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `forEach` function iterates over each element in an array-like object and calls a callback
+   * function for each element.
+   * @param callbackfn - The callbackfn parameter is a function that will be called for each element in
+   * the array. It takes three arguments: the current element being processed, the index of the current
+   * element, and the array that forEach was called upon.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
+   * be passed as the `this` value to the `callbackfn` function. If `thisArg
+   */
+  forEach(callbackfn: ElementCallback<V, void>, thisArg?: any): void {
+    let index = 0;
+    for (const item of this) {
+      callbackfn.call(thisArg, item as V, index++, this)
+    }
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `reduce` function iterates over the elements of an array-like object and applies a callback
+   * function to reduce them into a single value.
+   * @param callbackfn - The callbackfn parameter is a function that will be called for each element in
+   * the array. It takes four arguments:
+   * @param {U} initialValue - The initialValue parameter is the initial value of the accumulator. It
+   * is the value that the accumulator starts with before the reduction operation begins.
+   * @returns The `reduce` method is returning the final value of the accumulator after iterating over
+   * all the elements in the array and applying the callback function to each element.
+   */
+  reduce<U>(callbackfn: ReduceElementCallback<V, U>, initialValue: U): U {
+    let accumulator = initialValue;
+    let index = 0;
+    for (const item of this) {
+      accumulator = callbackfn(accumulator, item as V, index++, this)
+    }
+    return accumulator;
+  }
+
+  protected abstract _getIterator(...args: any[]): IterableIterator<V>;
+}

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

@@ -13,7 +13,7 @@ import type {
   BTNKey,
   BTNodeEntry,
   BTNodeExemplar,
-  BTNodeKeyOrNode
+  BTNodeKeyOrNode,
 } from '../../types';
 import {
   BinaryTreeNested,
@@ -22,11 +22,13 @@ import {
   DFSOrderPattern,
   FamilyPosition,
   IterationType,
-  NodeDisplayLayout
+  NodeDisplayLayout,
+  PairCallback
 } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 import { trampoline } from '../../utils';
 import { Queue } from '../queue';
+import { IterablePairBase } from "../base";
 
 /**
  * Represents a node in a binary tree.
@@ -102,9 +104,10 @@ export class BinaryTreeNode<V = any, N extends BinaryTreeNode<V, N> = BinaryTree
  * 8. Full Trees: Every node has either 0 or 2 children.
  * 9. Complete Trees: All levels are fully filled except possibly the last, filled from left to right.
  */
-export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode<V, BinaryTreeNodeNested<V>>, TREE extends BinaryTree<V, N, TREE> = BinaryTree<V, N, BinaryTreeNested<V, N>>>
-  implements IBinaryTree<V, N, TREE> {
 
+export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode<V, BinaryTreeNodeNested<V>>, TREE extends BinaryTree<V, N, TREE> = BinaryTree<V, N, BinaryTreeNested<V, N>>> extends IterablePairBase<BTNKey, V | undefined>
+
+  implements IBinaryTree<V, N, TREE> {
   iterationType = IterationType.ITERATIVE
 
   /**
@@ -117,7 +120,7 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    * required.
    */
   constructor(elements?: Iterable<BTNodeExemplar<V, N>>, options?: Partial<BinaryTreeOptions>) {
-
+    super();
     if (options) {
       const { iterationType } = options;
       if (iterationType) {
@@ -1725,33 +1728,48 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
 
   /**
    * Time complexity: O(n)
-   * Space complexity: O(1)
+   * Space complexity: O(n)
    */
 
   /**
-   * The `forEach` function iterates over each entry in a tree and calls a callback function with the
-   * entry and the tree as arguments.
-   * @param callback - The callback parameter is a function that will be called for each entry in the
-   * tree. It takes two parameters: entry and tree.
-   */
-  forEach(callback: (entry: [BTNKey, V | undefined], tree: this) => void): void {
-    for (const entry of this) {
-      callback(entry, this);
-    }
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   *
+   * The `clone` function creates a new tree object and copies all the nodes from the original tree to
+   * the new tree.
+   * @returns The `clone()` method is returning a cloned instance of the `TREE` object.
+   */
+  clone(): TREE {
+    const cloned = this.createTree();
+    this.bfs(node => cloned.add([node.key, node.value]));
+    return cloned;
   }
 
   /**
-   * The `filter` function creates a new tree by iterating over the entries of the current tree and
-   * adding the entries that satisfy the given predicate.
-   * @param predicate - The `predicate` parameter is a function that takes two arguments: `entry` and
-   * `tree`.
-   * @returns The `filter` method is returning a new tree object that contains only the entries that
-   * satisfy the given predicate function.
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
    */
-  filter(predicate: (entry: [BTNKey, V | undefined], tree: this) => boolean) {
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `filter` function creates a new tree by iterating over the elements of the current tree and
+   * adding only the elements that satisfy the given predicate function.
+   * @param predicate - The `predicate` parameter is a function that takes three arguments: `value`,
+   * `key`, and `index`. It should return a boolean value indicating whether the pair should be
+   * included in the filtered tree or not.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as the `this` value when executing the `predicate` function. If `thisArg` is provided,
+   * it will be passed as the first argument to the `predicate` function. If `thisArg` is
+   * @returns The `filter` method is returning a new tree object that contains the key-value pairs that
+   * pass the given predicate function.
+   */
+  filter(predicate: PairCallback<BTNKey, V | undefined, boolean>, thisArg?: any) {
     const newTree = this.createTree();
+    let index = 0;
     for (const [key, value] of this) {
-      if (predicate([key, value], this)) {
+      if (predicate.call(thisArg, value, key, index++, this)) {
         newTree.add([key, value]);
       }
     }
@@ -1759,58 +1777,74 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
   }
 
   /**
-   * The `map` function creates a new tree by applying a callback function to each entry in the current
-   * tree.
-   * @param callback - The callback parameter is a function that takes two arguments: entry and tree.
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   */
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `map` function creates a new tree by applying a callback function to each key-value pair in
+   * the original tree.
+   * @param callback - The callback parameter is a function that will be called for each key-value pair
+   * in the tree. It takes four arguments: the value of the current pair, the key of the current pair,
+   * the index of the current pair, and a reference to the tree itself. The callback function should
+   * return a new
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that allows you to
+   * specify the value of `this` within the callback function. If you pass a value for `thisArg`, it
+   * will be used as the `this` value when the callback function is called. If you don't pass a value
    * @returns The `map` method is returning a new tree object.
    */
-  map(callback: (entry: [BTNKey, V | undefined], tree: this) => V) {
+  map(callback: PairCallback<BTNKey, V | undefined, V>, thisArg?: any) {
     const newTree = this.createTree();
+    let index = 0;
     for (const [key, value] of this) {
-      newTree.add([key, callback([key, value], this)]);
+      newTree.add([key, callback.call(thisArg, value, key, index++, this)]);
     }
     return newTree;
   }
 
-  // TODO Type error, need to return a TREE<NV> that is a value type only for callback function.
-  // map<NV>(callback: (entry: [BTNKey, V | undefined], tree: this) => NV) {
-  //   const newTree = this.createTree();
-  //   for (const [key, value] of this) {
-  //     newTree.add(key, callback([key, value], this));
-  //   }
-  //   return newTree;
-  // }
-
-  /**
-   * The `reduce` function iterates over the entries of a tree and applies a callback function to each
-   * entry, accumulating a single value.
-   * @param callback - The callback parameter is a function that takes three arguments: accumulator,
-   * entry, and tree. It is called for each entry in the tree and is used to accumulate a single value
-   * based on the logic defined in the callback function.
-   * @param {T} initialValue - The initialValue parameter is the initial value of the accumulator. It
-   * is the value that will be passed as the first argument to the callback function when reducing the
-   * elements of the tree.
-   * @returns The `reduce` method is returning the final value of the accumulator after iterating over
-   * all the entries in the tree and applying the callback function to each entry.
-   */
-  reduce<T>(callback: (accumulator: T, entry: [BTNKey, V | undefined], tree: this) => T, initialValue: T): T {
-    let accumulator = initialValue;
-    for (const [key, value] of this) {
-      accumulator = callback(accumulator, [key, value], this);
-    }
-    return accumulator;
-  }
+  // // TODO Type error, need to return a TREE<NV> that is a value type only for callback function.
+  // // map<NV>(callback: (entry: [BTNKey, V | undefined], tree: this) => NV) {
+  // //   const newTree = this.createTree();
+  // //   for (const [key, value] of this) {
+  // //     newTree.add(key, callback([key, value], this));
+  // //   }
+  // //   return newTree;
+  // // }
+  //
 
   /**
-   * The above function is an iterator for a binary tree that can be used to traverse the tree in
-   * either an iterative or recursive manner.
-   * @param node - The `node` parameter represents the current node in the binary tree from which the
-   * iteration starts. It is an optional parameter with a default value of `this.root`, which means
-   * that if no node is provided, the iteration will start from the root of the binary tree.
-   * @returns The `*[Symbol.iterator]` method returns a generator object that yields the keys of the
-   * binary tree nodes in a specific order.
+   * The `print` function is used to display a binary tree structure in a visually appealing way.
+   * @param {BTNKey | N | null | undefined} [beginRoot=this.root] - The `root` parameter is of type `BTNKey | N | null |
+   * undefined`. It represents the root node of a binary tree. The root node can have one of the
+   * following types:
+   * @param {BinaryTreePrintOptions} [options={ isShowUndefined: false, isShowNull: false, isShowRedBlackNIL: false}] - Options object that controls printing behavior. You can specify whether to display undefined, null, or sentinel nodes.
    */
-  * [Symbol.iterator](node = this.root): Generator<[BTNKey, V | undefined], void, undefined> {
+  print(beginRoot: BTNodeKeyOrNode<N> = this.root, options?: BinaryTreePrintOptions): void {
+    const opts = { isShowUndefined: false, isShowNull: false, isShowRedBlackNIL: false, ...options };
+    beginRoot = this.ensureNode(beginRoot);
+    if (!beginRoot) return;
+
+    if (opts.isShowUndefined) console.log(`U for undefined
+      `);
+    if (opts.isShowNull) console.log(`N for null
+      `);
+    if (opts.isShowRedBlackNIL) console.log(`S for Sentinel Node
+      `);
+
+    const display = (root: N | null | undefined): void => {
+      const [lines, , ,] = this._displayAux(root, opts);
+      for (const line of lines) {
+        console.log(line);
+      }
+    };
+
+    display(beginRoot);
+  }
+
+  protected* _getIterator(node = this.root): IterableIterator<[BTNKey, V | undefined]> {
     if (!node) return;
 
     if (this.iterationType === IterationType.ITERATIVE) {
@@ -1841,35 +1875,6 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     }
   }
 
-  /**
-   * The `print` function is used to display a binary tree structure in a visually appealing way.
-   * @param {BTNKey | N | null | undefined} [beginRoot=this.root] - The `root` parameter is of type `BTNKey | N | null |
-   * undefined`. It represents the root node of a binary tree. The root node can have one of the
-   * following types:
-   * @param {BinaryTreePrintOptions} [options={ isShowUndefined: false, isShowNull: false, isShowRedBlackNIL: false}] - Options object that controls printing behavior. You can specify whether to display undefined, null, or sentinel nodes.
-   */
-  print(beginRoot: BTNodeKeyOrNode<N> = this.root, options?: BinaryTreePrintOptions): void {
-    const opts = { isShowUndefined: false, isShowNull: false, isShowRedBlackNIL: false, ...options };
-    beginRoot = this.ensureNode(beginRoot);
-    if (!beginRoot) return;
-
-    if (opts.isShowUndefined) console.log(`U for undefined
-      `);
-    if (opts.isShowNull) console.log(`N for null
-      `);
-    if (opts.isShowRedBlackNIL) console.log(`S for Sentinel Node
-      `);
-
-    const display = (root: N | null | undefined): void => {
-      const [lines, , ,] = this._displayAux(root, opts);
-      for (const line of lines) {
-        console.log(line);
-      }
-    };
-
-    display(beginRoot);
-  }
-
   protected _displayAux(node: N | null | undefined, options: BinaryTreePrintOptions): NodeDisplayLayout {
     const { isShowNull, isShowUndefined, isShowRedBlackNIL } = options;
     const emptyDisplayLayout = <NodeDisplayLayout>[['─'], 1, 0, 0];

package/src/data-structures/binary-tree/tree-multimap.ts

@@ -318,6 +318,24 @@ export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultim
     this._count = 0;
   }
 
+  /**
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   */
+
+  /**
+   * Time complexity: O(n)
+   * Space complexity: O(n)
+   *
+   * The `clone` function creates a deep copy of a tree object.
+   * @returns The `clone()` method is returning a cloned instance of the `TREE` object.
+   */
+  override clone(): TREE {
+    const cloned = this.createTree();
+    this.bfs(node => cloned.add([node.key, node.value], node.count));
+    return cloned;
+  }
+
   /**
    * Time Complexity: O(1) - constant time, as it performs basic pointer assignments.
    * Space Complexity: O(1) - constant space, as it only uses a constant amount of memory.