red-black-tree-typed 1.47.3

package/src/data-structures/hash/hash-map.ts

@@ -0,0 +1,401 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+
+import { isWeakKey, rangeCheck } from '../../utils';
+import { HashMapLinkedNode, HashMapOptions } from '../../types';
+
+export class HashMap<K = any, V = any> {
+
+  protected _noObjMap: Record<string, HashMapLinkedNode<K, V | undefined>> = {};
+  protected _objMap = new WeakMap<object, HashMapLinkedNode<K, V | undefined>>();
+  protected _head: HashMapLinkedNode<K, V | undefined>;
+  protected _tail: HashMapLinkedNode<K, V | undefined>;
+  protected readonly _sentinel: HashMapLinkedNode<K, V | undefined>;
+  protected _hashFn: (key: K) => string;
+  protected _objHashFn: (key: K) => object;
+
+  /**
+   * The constructor initializes a HashMapLinkedNode with an optional iterable of key-value pairs.
+   * @param options - The `options` parameter is an object that contains the `elements` property. The
+   * `elements` property is an iterable that contains key-value pairs represented as arrays `[K, V]`.
+   */
+  constructor(options: HashMapOptions<K, V> = {
+    elements: [],
+    hashFn: (key: K) => String(key),
+    objHashFn: (key: K) => (<object>key)
+  }) {
+    this._sentinel = <HashMapLinkedNode<K, V>>{};
+    this._sentinel.prev = this._sentinel.next = this._head = this._tail = this._sentinel;
+
+    const { elements, hashFn, objHashFn } = options;
+    this._hashFn = hashFn;
+    this._objHashFn = objHashFn;
+    if (elements) {
+      for (const el of elements) {
+        this.set(el[0], el[1]);
+      }
+    }
+
+  }
+
+  protected _size = 0;
+
+  get size() {
+    return this._size;
+  }
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The function returns the key-value pair at the front of a data structure.
+   * @returns The front element of the data structure, represented as a tuple with a key (K) and a
+   * value (V).
+   */
+  get first() {
+    if (this._size === 0) return;
+    return <[K, V]>[this._head.key, this._head.value];
+  }
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The function returns the key-value pair at the end of a data structure.
+   * @returns The method is returning an array containing the key-value pair of the tail element in the
+   * data structure.
+   */
+  get last() {
+    if (this._size === 0) return;
+    return <[K, V]>[this._tail.key, this._tail.value];
+  }
+
+  /**
+   * The `begin()` function in TypeScript iterates over a linked list and yields key-value pairs.
+   */
+  * begin() {
+    let node = this._head;
+    while (node !== this._sentinel) {
+      yield [node.key, node.value];
+      node = node.next;
+    }
+  }
+
+  /**
+   * The function `reverseBegin()` iterates over a linked list in reverse order, yielding each node's
+   * key and value.
+   */
+  * reverseBegin() {
+    let node = this._tail;
+    while (node !== this._sentinel) {
+      yield [node.key, node.value];
+      node = node.prev;
+    }
+  }
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The `set` function adds a new key-value pair to a data structure, either using an object key or a
+   * string key.
+   * @param {K} key - The `key` parameter is the key to be set in the data structure. It can be of any
+   * type, but typically it is a string or symbol.
+   * @param {V} [value] - The `value` parameter is an optional parameter of type `V`. It represents the
+   * value associated with the key being set in the data structure.
+   * @returns the size of the data structure after the key-value pair has been set.
+   */
+  set(key: K, value?: V) {
+    let node;
+
+    if (isWeakKey(key)) {
+      const hash = this._objHashFn(key);
+      node = this._objMap.get(hash);
+
+      if (node) {
+        // If the node already exists, update its value
+        node.value = value;
+      } else {
+        // Create new node
+        node = { key: <K>hash, value, prev: this._tail, next: this._sentinel };
+
+        // Add new nodes to _objMap and linked list
+        this._objMap.set(hash, node);
+      }
+    } else {
+      const hash = this._hashFn(key);
+      // Non-object keys are handled in the same way as the original implementation
+      node = this._noObjMap[hash];
+      if (node) {
+        node.value = value;
+      } else {
+        this._noObjMap[hash] = node = {
+          key,
+          value,
+          prev: this._tail,
+          next: this._sentinel
+        };
+      }
+    }
+
+    if (this._size === 0) {
+      this._head = node;
+      this._sentinel.next = node;
+    } else {
+      this._tail.next = node;
+    }
+
+    this._tail = node;
+    this._sentinel.prev = node;
+    this._size++;
+
+    return this._size;
+  }
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The function `get` retrieves the value associated with a given key from a map, either by using the
+   * key directly or by using an index stored in the key object.
+   * @param {K} key - The `key` parameter is the key used to retrieve a value from the map. It can be
+   * of any type, but typically it is a string or symbol.
+   * @returns The value associated with the given key is being returned. If the key is an object key,
+   * the value is retrieved from the `_nodes` array using the index stored in the `OBJ_KEY_INDEX`
+   * property of the key. If the key is a string key, the value is retrieved from the `_noObjMap` object
+   * using the key itself. If the key is not found, `undefined` is
+   */
+  get(key: K): V | undefined {
+    if (isWeakKey(key)) {
+      const hash = this._objHashFn(key);
+      const node = this._objMap.get(hash);
+      return node ? node.value : undefined;
+    } else {
+      const hash = this._hashFn(key);
+      const node = this._noObjMap[hash];
+      return node ? node.value : undefined;
+    }
+  }
+
+  /**
+   * Time Complexity: O(n), where n is the index.
+   * Space Complexity: O(1)
+   *
+   * The function `getAt` retrieves the key-value pair at a specified index in a linked list.
+   * @param {number} index - The index parameter is a number that represents the position of the
+   * element we want to retrieve from the data structure.
+   * @returns The method `getAt(index: number)` is returning an array containing the key-value pair at
+   * the specified index in the data structure. The key-value pair is represented as a tuple `[K, V]`,
+   * where `K` is the key and `V` is the value.
+   */
+  getAt(index: number) {
+    rangeCheck(index, 0, this._size - 1);
+    let node = this._head;
+    while (index--) {
+      node = node.next;
+    }
+    return <[K, V]>[node.key, node.value];
+  }
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The `delete` function removes a key-value pair from a map-like data structure.
+   * @param {K} key - The `key` parameter is the key that you want to delete from the data structure.
+   * It can be of any type, but typically it is a string or an object.
+   * @returns a boolean value. It returns `true` if the deletion was successful, and `false` if the key
+   * was not found.
+   */
+  delete(key: K) {
+    let node;
+
+    if (isWeakKey(key)) {
+      const hash = this._objHashFn(key);
+      // Get nodes from WeakMap
+      node = this._objMap.get(hash);
+
+      if (!node) {
+        return false; // If the node does not exist, return false
+      }
+
+      // Remove nodes from WeakMap
+      this._objMap.delete(hash);
+    } else {
+      const hash = this._hashFn(key);
+      // Get nodes from noObjMap
+      node = this._noObjMap[hash];
+
+      if (!node) {
+        return false; // If the node does not exist, return false
+      }
+
+      // Remove nodes from orgMap
+      delete this._noObjMap[hash];
+    }
+
+    // Remove node from doubly linked list
+    this._deleteNode(node);
+    return true;
+  }
+
+  /**
+   * Time Complexity: O(n), where n is the index.
+   * Space Complexity: O(1)
+   *
+   * The `deleteAt` function deletes a node at a specified index in a linked list.
+   * @param {number} index - The index parameter represents the position at which the node should be
+   * deleted in the linked list.
+   * @returns The size of the list after deleting the element at the specified index.
+   */
+  deleteAt(index: number) {
+    rangeCheck(index, 0, this._size - 1);
+    let node = this._head;
+    while (index--) {
+      node = node.next;
+    }
+    this._deleteNode(node);
+    return this._size;
+  }
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The function checks if a data structure is empty by comparing its size to zero.
+   * @returns The method is returning a boolean value indicating whether the size of the object is 0 or
+   * not.
+   */
+  isEmpty() {
+    return this._size === 0;
+  }
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The `clear` function clears all the elements in a data structure and resets its properties.
+   */
+  clear() {
+    this._noObjMap = {};
+    this._size = 0;
+    this._head = this._tail = this._sentinel.prev = this._sentinel.next = this._sentinel;
+  }
+
+  /**
+   * Time Complexity: O(n), where n is the number of elements in the HashMap.
+   * Space Complexity: O(1)
+   *
+   * The `forEach` function iterates over each element in a HashMap and executes a callback function on
+   * each element.
+   * @param callback - The callback parameter is a function that will be called for each element in the
+   * HashMap. It takes three arguments:
+   */
+  forEach(callback: (element: [K, V], index: number, hashMap: HashMap<K, V>) => void) {
+    let index = 0;
+    let node = this._head;
+    while (node !== this._sentinel) {
+      callback(<[K, V]>[node.key, node.value], index++, this);
+      node = node.next;
+    }
+  }
+
+  /**
+   * The `filter` function takes a predicate function and returns a new HashMap containing only the
+   * key-value pairs that satisfy the predicate.
+   * @param predicate - The `predicate` parameter is a function that takes two arguments: `element` and
+   * `map`.
+   * @returns a new HashMap object that contains the key-value pairs from the original HashMap that
+   * satisfy the given predicate function.
+   */
+  filter(predicate: (element: [K, V], map: HashMap<K, V>) => boolean): HashMap<K, V> {
+    const filteredMap = new HashMap<K, V>();
+    for (const [key, value] of this) {
+      if (predicate([key, value], this)) {
+        filteredMap.set(key, value);
+      }
+    }
+    return filteredMap;
+  }
+
+  /**
+   * The `map` function takes a callback function and returns a new HashMap with the values transformed
+   * by the callback.
+   * @param callback - The `callback` parameter is a function that takes two arguments: `element` and
+   * `map`.
+   * @returns a new HashMap object with the values mapped according to the provided callback function.
+   */
+  map<NV>(callback: (element: [K, V], map: HashMap<K, V>) => NV): HashMap<K, NV> {
+    const mappedMap = new HashMap<K, NV>();
+    for (const [key, value] of this) {
+      const newValue = callback([key, value], this);
+      mappedMap.set(key, newValue);
+    }
+    return mappedMap;
+  }
+
+  /**
+   * The `reduce` function iterates over the elements of a HashMap and applies a callback function to
+   * each element, accumulating a single value.
+   * @param callback - The callback parameter is a function that takes three arguments: accumulator,
+   * element, and map. It is called for each element in the HashMap and is used to accumulate a single
+   * result.
+   * @param {A} 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 map.
+   * @returns The `reduce` function is returning the final value of the accumulator after iterating
+   * over all the elements in the HashMap and applying the callback function to each element.
+   */
+  reduce<A>(callback: (accumulator: A, element: [K, V], map: HashMap<K, V>) => A, initialValue: A): A {
+    let accumulator = initialValue;
+    for (const element of this) {
+      accumulator = callback(accumulator, element, this);
+    }
+    return accumulator;
+  }
+
+  /**
+   * Time Complexity: O(n), where n is the number of elements in the HashMap.
+   * Space Complexity: O(1)
+   *
+   * The above function is an iterator that yields key-value pairs from a linked list.
+   */
+  * [Symbol.iterator]() {
+    let node = this._head;
+    while (node !== this._sentinel) {
+      yield <[K, V]>[node.key, node.value];
+      node = node.next;
+    }
+  }
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The `_deleteNode` function removes a node from a doubly linked list and updates the head and tail
+   * pointers if necessary.
+   * @param node - The `node` parameter is an instance of the `HashMapLinkedNode` class, which
+   * represents a node in a linked list. It contains a key-value pair and references to the previous
+   * and next nodes in the list.
+   */
+  protected _deleteNode(node: HashMapLinkedNode<K, V | undefined>) {
+    const { prev, next } = node;
+    prev.next = next;
+    next.prev = prev;
+
+    if (node === this._head) {
+      this._head = next;
+    }
+
+    if (node === this._tail) {
+      this._tail = prev;
+    }
+
+    this._size -= 1;
+  }
+}

package/src/data-structures/hash/hash-table.ts

@@ -0,0 +1,268 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+
+export class HashTableNode<K, V> {
+  key: K;
+  value: V;
+  next: HashTableNode<K, V> | null;
+
+  constructor(key: K, value: V) {
+    this.key = key;
+    this.value = value;
+    this.next = null;
+  }
+}
+
+import { HashFunction } from '../../types';
+
+export class HashTable<K, V> {
+  protected static readonly DEFAULT_CAPACITY = 16;
+  protected static readonly LOAD_FACTOR = 0.75;
+
+  constructor(capacity: number = HashTable.DEFAULT_CAPACITY, hashFn?: HashFunction<K>) {
+    this._hashFn = hashFn || this._defaultHashFn;
+    this._capacity = Math.max(capacity, HashTable.DEFAULT_CAPACITY);
+    this._size = 0;
+    this._buckets = new Array<HashTableNode<K, V> | null>(this._capacity).fill(null);
+  }
+
+  protected _capacity: number;
+
+  get capacity(): number {
+    return this._capacity;
+  }
+
+  protected _size: number;
+
+  get size(): number {
+    return this._size;
+  }
+
+  protected _buckets: Array<HashTableNode<K, V> | null>;
+
+  get buckets(): Array<HashTableNode<K, V> | null> {
+    return this._buckets;
+  }
+
+  protected _hashFn: HashFunction<K>;
+
+  get hashFn(): HashFunction<K> {
+    return this._hashFn;
+  }
+
+  /**
+   * The set function adds a key-value pair to the hash table, handling collisions and resizing if necessary.
+   * @param {K} key - The key parameter represents the key of the key-value pair that you want to insert into the hash
+   * table. It is of type K, which is a generic type representing the key's data type.
+   * @param {V} value - The parameter `value` represents the value that you want to associate with the given key in the hash
+   * table.
+   * @returns Nothing is being returned. The return type of the `put` method is `void`, which means it does not return any
+   * value.
+   */
+  set(key: K, value: V): void {
+    const index = this._hash(key);
+    const newNode = new HashTableNode<K, V>(key, value);
+
+    if (!this._buckets[index]) {
+      this._buckets[index] = newNode;
+    } else {
+      // Handle collisions, consider using open addressing, etc.
+      let currentNode = this._buckets[index]!;
+      while (currentNode) {
+        if (currentNode.key === key) {
+          // If the key already exists, update the value
+          currentNode.value = value;
+          return;
+        }
+        if (!currentNode.next) {
+          break;
+        }
+        currentNode = currentNode.next;
+      }
+      // Add to the end of the linked list
+      currentNode.next = newNode;
+    }
+    this._size++;
+
+    // If the load factor is too high, resize the hash table
+    if (this._size / this._capacity >= HashTable.LOAD_FACTOR) {
+      this._expand();
+    }
+  }
+
+  /**
+   * The `get` function retrieves the value associated with a given key from a hash table.
+   * @param {K} key - The `key` parameter represents the key of the element that we want to retrieve from the data
+   * structure.
+   * @returns The method is returning the value associated with the given key if it exists in the hash table. If the key is
+   * not found, it returns `undefined`.
+   */
+  get(key: K): V | undefined {
+    const index = this._hash(key);
+    let currentNode = this._buckets[index];
+
+    while (currentNode) {
+      if (currentNode.key === key) {
+        return currentNode.value;
+      }
+      currentNode = currentNode.next;
+    }
+    return undefined; // Key not found
+  }
+
+  /**
+   * The delete function removes a key-value pair from a hash table.
+   * @param {K} key - The `key` parameter represents the key of the key-value pair that needs to be removed from the hash
+   * table.
+   * @returns Nothing is being returned. The `delete` method has a return type of `void`, which means it does not return
+   * any value.
+   */
+  delete(key: K): void {
+    const index = this._hash(key);
+    let currentNode = this._buckets[index];
+    let prevNode: HashTableNode<K, V> | null = null;
+
+    while (currentNode) {
+      if (currentNode.key === key) {
+        if (prevNode) {
+          prevNode.next = currentNode.next;
+        } else {
+          this._buckets[index] = currentNode.next;
+        }
+        this._size--;
+        currentNode.next = null; // Release memory
+        return;
+      }
+      prevNode = currentNode;
+      currentNode = currentNode.next;
+    }
+  }
+
+  /**
+   * The function `_defaultHashFn` calculates the hash value of a given key and returns the remainder when divided by the
+   * capacity of the data structure.
+   * @param {K} key - The `key` parameter is the input value that needs to be hashed. It can be of any type, but in this
+   * code snippet, it is checked whether the key is a string or an object. If it is a string, the `_murmurStringHashFn`
+   * function is used to
+   * @returns the hash value of the key modulo the capacity of the data structure.
+   */
+  protected _defaultHashFn(key: K): number {
+    // Can be replaced with other hash functions as needed
+    const hashValue = typeof key === 'string' ? this._murmurStringHashFn(key) : this._objectHash(key);
+    return hashValue % this._capacity;
+  }
+
+  /**
+   * The `_multiplicativeStringHashFn` function calculates a hash value for a given string key using the multiplicative
+   * string hash function.
+   * @param {K} key - The `key` parameter is the input value for which we want to calculate the hash. It can be of any
+   * type, as it is generic (`K`). The function converts the `key` to a string using the `String()` function.
+   * @returns a number, which is the result of the multiplicative string hash function applied to the input key.
+   */
+  protected _multiplicativeStringHashFn<K>(key: K): number {
+    const keyString = String(key);
+    let hash = 0;
+    for (let i = 0; i < keyString.length; i++) {
+      const charCode = keyString.charCodeAt(i);
+      // Some constants for adjusting the hash function
+      const A = 0.618033988749895;
+      const M = 1 << 30; // 2^30
+      hash = (hash * A + charCode) % M;
+    }
+    return Math.abs(hash); // Take absolute value to ensure non-negative numbers
+  }
+
+  /**
+   * The function `_murmurStringHashFn` calculates a hash value for a given string key using the MurmurHash algorithm.
+   * @param {K} key - The `key` parameter is the input value for which you want to calculate the hash. It can be of any
+   * type, but it will be converted to a string using the `String()` function before calculating the hash.
+   * @returns a number, which is the hash value calculated for the given key.
+   */
+  protected _murmurStringHashFn<K>(key: K): number {
+    const keyString = String(key);
+    const seed = 0;
+    let hash = seed;
+
+    for (let i = 0; i < keyString.length; i++) {
+      const char = keyString.charCodeAt(i);
+      hash = (hash ^ char) * 0x5bd1e995;
+      hash = (hash ^ (hash >>> 15)) * 0x27d4eb2d;
+      hash = hash ^ (hash >>> 15);
+    }
+
+    return Math.abs(hash);
+  }
+
+  /**
+   * The _hash function takes a key and returns a number.
+   * @param {K} key - The parameter "key" is of type K, which represents the type of the key that will be hashed.
+   * @returns The hash function is returning a number.
+   */
+  protected _hash(key: K): number {
+    return this.hashFn(key);
+  }
+
+  /**
+   * The function calculates a hash value for a given string using the djb2 algorithm.
+   * @param {string} key - The `key` parameter in the `stringHash` function is a string value that represents the input for
+   * which we want to calculate the hash value.
+   * @returns a number, which is the hash value of the input string.
+   */
+  protected _stringHash(key: string): number {
+    let hash = 0;
+    for (let i = 0; i < key.length; i++) {
+      hash = (hash * 31 + key.charCodeAt(i)) & 0xffffffff;
+    }
+    return hash;
+  }
+
+  /**
+   * The function `_objectHash` takes a key and returns a hash value, using a custom hash function for objects.
+   * @param {K} key - The parameter "key" is of type "K", which means it can be any type. It could be a string, number,
+   * boolean, object, or any other type of value. The purpose of the objectHash function is to generate a hash value for
+   * the key, which can be used for
+   * @returns a number, which is the hash value of the key.
+   */
+  protected _objectHash(key: K): number {
+    // If the key is an object, you can write a custom hash function
+    // For example, convert the object's properties to a string and use string hashing
+    // This is just an example; you should write a specific object hash function as needed
+    return this._stringHash(JSON.stringify(key));
+  }
+
+  /**
+   * The `expand` function increases the capacity of a hash table by creating a new array of buckets with double the
+   * capacity and rehashing all the existing key-value pairs into the new buckets.
+   */
+  protected _expand(): void {
+    const newCapacity = this._capacity * 2;
+    const newBuckets = new Array<HashTableNode<K, V> | null>(newCapacity).fill(null);
+
+    for (const bucket of this._buckets) {
+      let currentNode = bucket;
+      while (currentNode) {
+        const newIndex = this._hash(currentNode.key);
+        const newNode = new HashTableNode<K, V>(currentNode.key, currentNode.value);
+
+        if (!newBuckets[newIndex]) {
+          newBuckets[newIndex] = newNode;
+        } else {
+          let currentNewNode = newBuckets[newIndex]!;
+          while (currentNewNode.next) {
+            currentNewNode = currentNewNode.next;
+          }
+          currentNewNode.next = newNode;
+        }
+        currentNode = currentNode.next;
+      }
+    }
+
+    this._buckets = newBuckets;
+    this._capacity = newCapacity;
+  }
+}

package/src/data-structures/hash/index.ts

@@ -0,0 +1,2 @@
+export * from './hash-table';
+export * from './hash-map';