- implement Heap Sort Algorithm

Author: Isaac Ramirez

src/algorithms/heap-sort/heap-sort.client.js

@@ -0,0 +1,43 @@
+const Heap = require('./heap-sort')
+const { StdIn } = require('../../libs')
+
+/**
+ * Heap Sort Test Client.
+ * @memberof module:TestClients
+ * @see page: 324.
+ * @see [edu.princeton.cs.algs4.Heap.java]{@link https://algs4.cs.princeton.edu/code/edu/princeton/cs/algs4/Heap.java.html}
+ */
+class HeapSortClient {
+  /**
+   * Runs the Heap Sort Algorithm
+   * with the input provided.
+   * @example <caption>Tiny Example</caption>
+   * {@lang bash}
+   * $ ./client HeapSortClient < algs4-data/tiny.txt
+   * A E E L M O P R S T X
+   * @example <caption>Words3 Example</caption>
+   * {@lang bash}
+   * $ ./client HeapSortClient < algs4-data/words3.txt
+   * all bad bed bug dad ... yes yet zoo
+   */
+  static main () {
+    let array = []
+
+    // read all strings from standard input.
+    StdIn.read()
+      .on('line', line => {
+        array = array.concat(line.trim().split(' '))
+      })
+      .on('close', () => {
+        Heap.sort(array)
+
+        if (!Heap.isSorted(array)) {
+          throw new Error('array is NOT sorted')
+        }
+
+        Heap.show(array)
+      })
+  }
+}
+
+module.exports = { HeapSortClient }

src/algorithms/heap-sort/heap-sort.js

@@ -0,0 +1,66 @@
+const { GenericSort } = require('../../abstracts')
+
+/**
+ * Heap Sort Algorithm.
+ * @augments GenericSort
+ * @memberof module:Algorithms
+ * @see page: 324.
+ * @see [edu.princeton.cs.algs4.Heap.java]{@link https://algs4.cs.princeton.edu/code/edu/princeton/cs/algs4/Heap.java.html}
+ */
+class Heap extends GenericSort {
+  /**
+   * Implementation of Heap Sort algorithm.
+   * @param {Array<*>} a - The array of values to be sorted.
+   * @param {ComparatorFn} [comparator] - The comparator function.
+   */
+  static sort (a, comparator) {
+    let n = a.length
+
+    // constructs the max heap from the first half of the array
+    for (let k = Math.floor(n / 2); k >= 1; k--) {
+      this.sink(a, k, n, comparator)
+    }
+
+    // sort down
+    while (n > 1) {
+      // decrement indices by 1 so the array
+      // can be sorted from a[0] to a[n - 1]
+      this.exchange(a, 1 - 1, n - 1)
+      this.sink(a, 1, --n)
+    }
+  }
+
+  /**
+   * Sink algorithm. Restores the heap order by exchanging the node `k`
+   * down to the tree until is no longer smaller than any of its children.
+   * @param {Array<*>} a - The array of values treated also as the binary heap.
+   * @param {number} k - The index of the heap to sink.
+   * @param {number} n - The max length of the heap in which sink should run.
+   * @param {ComparatorFn} [comparator] - The comparator function.
+   */
+  static sink (a, k, n, comparator) {
+    while (2 * k <= n) {
+      let j = 2 * k
+
+      // decrement indices by 1 so the array
+      // can be sorted from a[0] to a[n - 1]
+      if (j < n && this.less(a[j - 1], a[j + 1 - 1], comparator)) {
+        j++
+      }
+
+      // decrement indices by 1 so the array
+      // can be sorted from a[0] to a[n - 1]
+      if (!this.less(a[k - 1], a[j - 1], comparator)) {
+        break
+      }
+
+      // decrement indices by 1 so the array
+      // can be sorted from a[0] to a[n - 1]
+      this.exchange(a, k - 1, j - 1)
+
+      k = j
+    }
+  }
+}
+
+module.exports = Heap

src/algorithms/heap-sort/heap-sort.spec.js

@@ -0,0 +1,118 @@
+const Heap = require('./heap-sort')
+const { newArrayOf } = require('../../utils')
+const { StdRandom } = require('../../libs')
+
+describe('Unit Tests: HeapSort', () => {
+  describe('Heap.sort()', () => {
+    it('should sort an ordered array', () => {
+      const orderedArray = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+      const expectedArray = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+      Heap.sort(orderedArray)
+
+      expect(orderedArray).toEqual(expectedArray)
+    })
+
+    it('should sort a reversed array', () => {
+      const reversedArray = [9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
+      const expectedArray = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+      Heap.sort(reversedArray)
+
+      expect(reversedArray).toEqual(expectedArray)
+    })
+
+    it('should sort an unordered array', () => {
+      const unorderedArray = [0, 9, 5, 2, 1, 8, 7, 6, 4, 3]
+      const expectedArray = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+      Heap.sort(unorderedArray)
+
+      expect(unorderedArray).toEqual(expectedArray)
+    })
+
+    it('should sort an array with all equal values', () => {
+      const allEqualArray = [9, 9, 9, 9, 9, 9, 9, 9, 9, 9]
+      const expectedArray = [9, 9, 9, 9, 9, 9, 9, 9, 9, 9]
+
+      Heap.sort(allEqualArray)
+
+      expect(allEqualArray).toEqual(expectedArray)
+    })
+
+    it('should sort a small random array', () => {
+      const n = CONFIG.SMALL_ARRAY_LENGTH
+      const array = newArrayOf(n, () => StdRandom.uniform(n))
+
+      Heap.sort(array)
+
+      expect(Heap.isSorted(array)).toBeTrue()
+    })
+
+    it('should sort a medium random array', () => {
+      const n = CONFIG.MEDIUM_ARRAY_LENGTH
+      const array = newArrayOf(n, () => StdRandom.uniform(n))
+
+      Heap.sort(array)
+
+      expect(Heap.isSorted(array)).toBeTrue()
+    })
+
+    it('should sort a large random array', () => {
+      const n = CONFIG.LARGE_ARRAY_LENGTH
+      const array = newArrayOf(n, () => StdRandom.uniform(n))
+
+      Heap.sort(array)
+
+      expect(Heap.isSorted(array)).toBeTrue()
+    })
+  })
+})
+
+describe('Explain me: HeapSort', () => {
+  it('should perform n exchanges and mutate the array', () => {
+    const a = [8, 9, 6, 5, 7, 4]
+    const mutations = [[...a]] // initial state
+    const originalExchange = Heap.exchange.bind(Heap)
+    spyOn(Heap, 'sink').and.callThrough()
+    spyOn(Heap, 'exchange').and.callFake((array, i, j) => {
+      originalExchange(array, i, j)
+      mutations.push([...array])
+    })
+    const expectedExchanges = [
+      [a, 0, 1], // exch 1: 8 <-> 9  : heap construction
+      [a, 0, 5], // exch 2: 9 <-> 4  : max goes to the end
+      [a, 0, 1], // exch 3: 4 <-> 8  : sink
+      [a, 1, 4], // exch 4: 4 <-> 7  :
+      [a, 0, 4], // exch 5: 8 <-> 4  : max goes to the end
+      [a, 0, 1], // exch 6: 4 <-> 7  : sink
+      [a, 1, 3], // exch 7: 4 <-> 5  :
+      [a, 0, 3], // exch 8: 7 <-> 4  : max goes to the end
+      [a, 0, 2], // exch 9: 4 <-> 6  : sink
+      [a, 0, 2], // exch 10: 6 <-> 4 : max goes to the end
+      [a, 0, 1], // exch 11: 4 <-> 5 : sink
+      [a, 0, 1] // exch 12: 5 <-> 4  : max goes to the end, sink
+    ]
+    const expectedMutations = [
+      [8, 9, 6, 5, 7, 4], // initial state
+      [9, 8, 6, 5, 7, 4], // exch 1
+      [4, 8, 6, 5, 7, 9], // exch 2
+      [8, 4, 6, 5, 7, 9], // exch 3
+      [8, 7, 6, 5, 4, 9], // exch 4
+      [4, 7, 6, 5, 8, 9], // exch 5
+      [7, 4, 6, 5, 8, 9], // exch 6
+      [7, 5, 6, 4, 8, 9], // exch 7
+      [4, 5, 6, 7, 8, 9], // exch 8
+      [6, 5, 4, 7, 8, 9], // exch 9
+      [4, 5, 6, 7, 8, 9], // exch 10
+      [5, 4, 6, 7, 8, 9], // exch 11
+      [4, 5, 6, 7, 8, 9] //  exch 12
+    ]
+
+    Heap.sort(a)
+
+    expect(Heap.exchange.calls.allArgs()).toEqual(expectedExchanges)
+    expect(Heap.sink).toHaveBeenCalledTimes(8)
+    expect(mutations).toEqual(expectedMutations)
+  })
+})

src/examples/test-clients/sort-compare.client.js

@@ -71,15 +71,15 @@ class SortCompare {
    * For 100000 random Doubles
    *     Quick3way is 2.0 times faster than Quick
    *
-   * @example <caption>Quick vs. Heap</caption>
+   * @example <caption>Heap vs. Quick</caption>
    * {@lang bash}
-   * $ ./client SortCompare Quick Heap 100000 100
+   * $ ./client SortCompare Heap Quick 100000 100
    *
-   * Quick: 2.523999999999998
-   * Heap: 21.244
+   * Heap: 6.8640000000000025
+   * Quick: 2.0819999999999985
    *
    * For 100000 random Doubles
-   *     Quick is 8.4 times faster than Heap
+   *     Heap is 0.3 times faster than Quick
    *
    * @param {...string} args - Params: `[algorithmName1, algorithmName2, n, trials]`
    * * @type {string} `args[0]` - Name of the first sorting algorithm.