hashmap iterators

Author: amejiarosario

README.md

@@ -37,4 +37,5 @@ alert('foo');
 /* eslint-disable no-alert, no-console */
 alert('foo');
 console.log('bar');
-/* e
+/* eslint-enable no-alert */
+```

benchmarks/hashmap.perf.js

@@ -130,12 +130,18 @@ function useBenchmark() {
   suite
 
   /*
-      ======== Results ========
-    490.84 ops/s with HashMap
-    293.756 ops/s with HashMap3
-    64.091 ops/s with HashMap4
+    ======== Results ========
+    2,653.472 ops/s with Map (built-in)
+    469.016 ops/s with HashMap
+    355.064 ops/s with HashMap3
+    66.808 ops/s with HashMap4
   */
 
+  suite.add('Map (built-in)', function() {
+    const map = new Map();
+    testMapOperations(map);
+  })
+
   // HashMap3 x 543 ops/sec ±1.53% (84 runs sampled)
   suite.add('HashMap3', function() {
     map = new HashMap3();
@@ -156,7 +162,7 @@ function useBenchmark() {
   // add listeners
   .on('cycle', function(event) {
     console.log(String(event.target));
-    if (map.collisions) {
+    if (map && map.collisions) {
       console.log('\tcollisions', map.collisions);
     }
   })

src/data-structures/hash-maps/hashmap.js

@@ -1,10 +1,21 @@
+/* eslint-disable no-bitwise, no-iterator, no-restricted-syntax */
 const LinkedList = require('../linked-lists/linked-list');
 const { nextPrime } = require('./primes');
 
+/**
+ * The Map object holds key-value pairs.
+ * Any value (both objects and primitive values) may be used as either a key or a value.
+ *
+ * Features:
+ * - HashMap offers avg. 0(1) lookup, insertion and deletion.
+ * - Keys and values are ordered by their insertion order (like Java's LinkedHashMap)
+ * - It contains only unique key.
+ * - It may have one null key and multiple null values.
+ */
 class HashMap {
   /**
    * Initialize array that holds the values.
-   * @param {number} initialCapacity initial size of the array
+   * @param {number} initialCapacity initial size of the array (should be a prime)
    * @param {number} loadFactor if set, the Map will automatically
    *  rehash when the load factor threshold is met
    */
@@ -28,88 +39,109 @@ class HashMap {
     this.keysTrackerIndex = keysTrackerIndex;
   }
 
-  set(key, value) {
-    const index = this.hashFunction(key);
-    this.setBucket(index, key, value);
-    return this;
-  }
-
-  get(key) {
-    const index = this.hashFunction(key);
-    const bucket = this.getBucket(index, key);
-    return bucket && bucket.value;
-  }
-
-  has(key) {
-    const index = this.hashFunction(key);
-    const bucket = this.getBucket(index, key);
-    return bucket !== undefined;
-  }
-
-  delete(key) {
-    const index = this.hashFunction(key);
-    return this.removeBucket(index, key);
-  }
-
   /**
-   * Uses FVN-1a hashing algorithm for 32 bits
+   * Polynomial hash codes are used to hash String typed keys.
+   *
+   * It uses FVN-1a hashing algorithm for 32 bits
    * @see https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function
    * @param {any} key
    * @return {integer} bucket index
    */
   hashFunction(key) {
-    const str = key.toString();
-    let hash = 2166136261;
+    const str = String(key);
+    let hash = 2166136261; // FNV_offset_basis (32 bit)
     for (let i = 0; i < str.length; i += 1) {
-      hash ^= str.codePointAt(i); // eslint-disable-line no-bitwise
-      hash *= 16777619;
+      hash ^= str.codePointAt(i);
+      hash *= 16777619; // 32 bit FNV_prime
     }
-    return (hash >>> 0) % this.buckets.length; // eslint-disable-line no-bitwise
+    return (hash >>> 0) % this.buckets.length;
   }
 
-  setBucket(index, key, value) {
-    this.buckets[index] = this.buckets[index] || new LinkedList();
-    const bucket = this.buckets[index];
-    // update value if key already exists
-    const hasKey = bucket.find(({ value: data }) => {
-      if (key === data.key) {
-        data.value = value; // update value
-        return true;
+  /**
+   * Find an entry inside a bucket.
+   *
+   * The bucket is an array of LinkedList.
+   * Entries are each of the nodes in the linked list.
+   *
+   * Avg. Runtime: O(1)
+   * If there are many collisions it could be O(n).
+   *
+   * @param {any} key
+   * @param {function} callback (optional) operation to
+   *  perform once the entry has been found
+   * @returns {any} entry (LinkedList's node's value)
+   */
+  getEntry(key, callback = () => {}) {
+    const index = this.hashFunction(key);
+    const bucket = this.buckets[index] || new LinkedList();
+    return bucket.find(({ value: entry }) => {
+      if (key === entry.key) {
+        callback(entry);
+        return entry;
       }
       return undefined;
     });
-    // add key/value if it doesn't find the key
-    if (!hasKey) {
-      bucket.push({
-        key,
-        value,
-        order: this.keysTrackerIndex,
-      });
+  }
+
+  /**
+   * Insert a key/value pair into the hash map.
+   * If the key is already there replaces its content.
+   * Avg. Runtime: O(1)
+   * In the case a rehash is needed O(n).
+   * @param {any} key
+   * @param {any} value
+   * @returns {HashMap} Return the Map object to allow chaining
+   */
+  set(key, value) {
+    const index = this.hashFunction(key);
+    this.buckets[index] = this.buckets[index] || new LinkedList();
+    const bucket = this.buckets[index];
+
+    const found = this.getEntry(key, (entry) => {
+      entry.value = value; // update value if key already exists
+    });
+
+    if (!found) { // add key/value if it doesn't find the key
+      bucket.push({ key, value, order: this.keysTrackerIndex });
       this.keysTrackerArray[this.keysTrackerIndex] = key;
       this.keysTrackerIndex += 1;
       this.size += 1;
-      // count collisions
-      if (bucket.size > 1) {
-        this.collisions += 1;
-      }
-
-      if (this.isBeyondloadFactor()) {
-        this.rehash();
-      }
+      if (bucket.size > 1) { this.collisions += 1; }
+      if (this.isBeyondloadFactor()) { this.rehash(); }
     }
+    return this;
   }
 
-  getBucket(index, key) {
-    const bucket = this.buckets[index] || new LinkedList();
-    return bucket.find(({ value: data }) => {
-      if (key === data.key) {
-        return data;
-      }
-      return undefined;
-    });
+  /**
+   * Gets the value out of the hash map
+   *
+   * @param {any} key
+   * @returns {any} value associated to the key, or undefined if there is none.
+   */
+  get(key) {
+    const bucket = this.getEntry(key);
+    return bucket && bucket.value;
+  }
+
+  /**
+   * Search for key and return true if it was found
+   * @param {any} key
+   * @returns {boolean} indicating whether an element
+   *  with the specified key exists or not.
+   */
+  has(key) {
+    const bucket = this.getEntry(key);
+    return bucket !== undefined;
   }
 
-  removeBucket(index, key) {
+  /**
+   * Removes the specified element from a Map object.
+   * @param {*} key
+   * @returns {boolean} true if an element in the Map object existed
+   *  and has been removed, or false if the element did not exist.
+   */
+  delete(key) {
+    const index = this.hashFunction(key);
     const bucket = this.buckets[index];
 
     if (!bucket || bucket.size === 0) {
@@ -126,28 +158,36 @@ class HashMap {
     });
   }
 
+  /**
+   * Load factor - measure how full the Map is.
+   * It's ratio between items on the map and total size of buckets
+   */
   getLoadFactor() {
     return this.size / this.buckets.length;
   }
 
+  /**
+   * Check if a rehash is due
+   */
   isBeyondloadFactor() {
     return this.getLoadFactor() > this.loadFactor;
   }
 
   /**
-   * @returns keys without holes (empty spaces of deleted keys)
+   * Rehash means to create a new Map with a new (higher)
+   *  capacity with the purpose of outgrow collisions.
+   * @param {integer} newBucketSize new bucket size by default
+   *  is the 2x the amount of data or bucket size.
    */
-  keys() {
-    return Object.values(this.keysTrackerArray);
-  }
-
   rehash(newBucketSize = Math.max(this.size, this.buckets.length) * 2) {
     const newCapacity = nextPrime(newBucketSize);
     const newMap = new HashMap(newCapacity);
-    this.keys().forEach((key) => {
+
+    for (const key of this.keys()) {
       newMap.set(key, this.get(key));
-    });
-    const newArrayKeys = newMap.keys();
+    }
+
+    const newArrayKeys = Array.from(newMap.keys());
 
     this.reset(
       newMap.buckets,
@@ -157,6 +197,54 @@ class HashMap {
       newArrayKeys.length,
     );
   }
+
+  /**
+   * Keys for each element in the Map object in insertion order.
+   * @returns {Iterator} keys without holes (empty spaces of deleted keys)
+   */
+  * keys() {
+    for (let index = 0; index < this.keysTrackerArray.length; index++) {
+      const key = this.keysTrackerArray[index];
+      if (key !== undefined) {
+        yield key;
+      }
+    }
+  }
+
+  /**
+   * Values for each element in the Map object in insertion order.
+   * @returns {Iterator} values without holes (empty spaces of deleted values)
+   */
+  * values() {
+    for (const key of this.keys()) {
+      yield this.get(key);
+    }
+  }
+
+  /**
+   * Contains the [key, value] pairs for each element in the Map object in insertion order.
+   * @returns {Iterator}
+   */
+  * entries() {
+    for (const key of this.keys()) {
+      yield [key, this.get(key)];
+    }
+  }
+
+  /**
+   * the same function object as the initial value of the `entries` method.
+   * Contains the [key, value] pairs for each element in the Map.
+   */
+  * [Symbol.iterator]() {
+    yield* this.entries();
+  }
+
+  /**
+   * @returns {integer} number of elements in the hashmap
+   */
+  get length() {
+    return this.size;
+  }
 }
 
 module.exports = HashMap;