Add heapify method with api docs

Author: AhmedLSayed9

data_structures/non_linear/trees/heaps/max_binary_heap.dart

@@ -3,7 +3,31 @@ import 'package:test/test.dart';
 import '../../../../utils/list_extension.dart';
 
 class MaxBinaryHeap {
-  final List<num> _heap = [];
+  MaxBinaryHeap() : _heap = [];
+
+  MaxBinaryHeap.buildFromArray(this._heap) {
+    _heapify();
+  }
+
+  final List<num> _heap;
+
+  /// Heapify describes the act of taking an existing, unordered array, and transforming it into a Heap structure.
+  /// What makes this process intriguing, is that if implemented well, it can be done in place, meaning O(1) space,
+  /// and in linear O(n) time versus the expected O(n log n) time "The naive iterate & insert approach".
+  ///
+  /// The reason why the _heapify() method starts at i = (_heap.length ~/ 2) - 1
+  /// is because this is the index of the last non-leaf node in the heap.
+  /// Starting from the last non-leaf node, sift it down and working backwards ensures
+  /// that each node in the heap is visited exactly once during the heapify process.
+  ///
+  /// Iterate over the array and insert VS overriding the heap array and calling siftDown()
+  /// for each non-leaf node: https://gist.github.com/AhmedLSayed9/968ba2811252f9bb135f4bd8db311ae1
+  void _heapify() {
+    final startingParent = (_heap.length ~/ 2) - 1;
+    for (int i = startingParent; i >= 0; i--) {
+      _siftDown(i);
+    }
+  }
 
   /// Pseudocode:
   /// - Push the value into the values property on the heap.
@@ -48,29 +72,28 @@ class MaxBinaryHeap {
 
     _heap.swap(0, _heap.length - 1);
     final oldRoot = _heap.removeLast();
-    _siftDown();
+    _siftDown(0);
     return oldRoot;
   }
 
-  _siftDown() {
-    int parentIndex = 0;
+  /// _siftDown() is responsible for swapping the current item with its largest
+  /// child (if any), and recursively calling itself on the new child index
+  /// until the current item is in its correct position.
+  _siftDown(int parentIndex) {
+    final leftChildIndex = parentIndex * 2 + 1;
+    final rightChildIndex = leftChildIndex + 1;
 
-    while (true) {
-      final leftChildIndex = parentIndex * 2 + 1;
-      final rightChildIndex = leftChildIndex + 1;
+    if (leftChildIndex >= _heap.length) return;
 
-      if (leftChildIndex >= _heap.length) break;
+    final maxChildIndex = rightChildIndex < _heap.length &&
+            _heap[rightChildIndex] > _heap[leftChildIndex]
+        ? rightChildIndex
+        : leftChildIndex;
 
-      final maxChildIndex = rightChildIndex < _heap.length &&
-              _heap[rightChildIndex] > _heap[leftChildIndex]
-          ? rightChildIndex
-          : leftChildIndex;
+    if (_heap[maxChildIndex] <= _heap[parentIndex]) return;
 
-      if (_heap[maxChildIndex] <= _heap[parentIndex]) break;
-
-      _heap.swap(parentIndex, maxChildIndex);
-      parentIndex = maxChildIndex;
-    }
+    _heap.swap(parentIndex, maxChildIndex);
+    _siftDown(maxChildIndex);
   }
 }
 
@@ -118,4 +141,17 @@ void main() {
       expect(heap.extract(), isNull);
     });
   });
+
+  group('heapify', () {
+    test('should convert the list into MaxBinaryHeap', () {
+      //         2
+      //     1      6
+      //   3   5
+      final heap = MaxBinaryHeap.buildFromArray([2, 1, 6, 3, 5]);
+      //         6
+      //     5      2
+      //   3   1
+      expect(heap._heap, [6, 5, 2, 3, 1]);
+    });
+  });
 }

data_structures/non_linear/trees/heaps/min_binary_heap.dart

@@ -3,7 +3,31 @@ import 'package:test/test.dart';
 import '../../../../utils/list_extension.dart';
 
 class MinBinaryHeap {
-  final List<num> _heap = [];
+  MinBinaryHeap() : _heap = [];
+
+  MinBinaryHeap.buildFromArray(this._heap) {
+    _heapify();
+  }
+
+  final List<num> _heap;
+
+  /// Heapify describes the act of taking an existing, unordered array, and transforming it into a Heap structure.
+  /// What makes this process intriguing, is that if implemented well, it can be done in place, meaning O(1) space,
+  /// and in linear O(n) time versus the expected O(n log n) time "The naive iterate & insert approach".
+  ///
+  /// The reason why the _heapify() method starts at i = (_heap.length ~/ 2) - 1
+  /// is because this is the index of the last non-leaf node in the heap.
+  /// Starting from the last non-leaf node, sift it down and working backwards ensures
+  /// that each node in the heap is visited exactly once during the heapify process.
+  ///
+  /// Iterate over the array and insert VS overriding the heap array and calling siftDown()
+  /// for each non-leaf node: https://gist.github.com/AhmedLSayed9/968ba2811252f9bb135f4bd8db311ae1
+  void _heapify() {
+    final startingParent = (_heap.length ~/ 2) - 1;
+    for (int i = startingParent; i >= 0; i--) {
+      _siftDown(i);
+    }
+  }
 
   /// Pseudocode:
   /// - Push the value into the values property on the heap.
@@ -48,29 +72,28 @@ class MinBinaryHeap {
 
     _heap.swap(0, _heap.length - 1);
     final oldRoot = _heap.removeLast();
-    _siftDown();
+    _siftDown(0);
     return oldRoot;
   }
 
-  _siftDown() {
-    int parentIndex = 0;
+  /// _siftDown() is responsible for swapping the current item with its smallest
+  /// child (if any), and recursively calling itself on the new child index
+  /// until the current item is in its correct position.
+  _siftDown(int parentIndex) {
+    final leftChildIndex = parentIndex * 2 + 1;
+    final rightChildIndex = leftChildIndex + 1;
 
-    while (true) {
-      final leftChildIndex = parentIndex * 2 + 1;
-      final rightChildIndex = leftChildIndex + 1;
+    if (leftChildIndex >= _heap.length) return;
 
-      if (leftChildIndex >= _heap.length) break;
+    final minChildIndex = rightChildIndex < _heap.length &&
+            _heap[rightChildIndex] < _heap[leftChildIndex]
+        ? rightChildIndex
+        : leftChildIndex;
 
-      final maxChildIndex = rightChildIndex < _heap.length &&
-              _heap[rightChildIndex] < _heap[leftChildIndex]
-          ? rightChildIndex
-          : leftChildIndex;
+    if (_heap[minChildIndex] >= _heap[parentIndex]) return;
 
-      if (_heap[maxChildIndex] >= _heap[parentIndex]) break;
-
-      _heap.swap(parentIndex, maxChildIndex);
-      parentIndex = maxChildIndex;
-    }
+    _heap.swap(parentIndex, minChildIndex);
+    _siftDown(minChildIndex);
   }
 }
 
@@ -117,5 +140,18 @@ void main() {
 
       expect(heap.extract(), isNull);
     });
+
+    group('heapify', () {
+      test('should convert the list into MinBinaryHeap', () {
+        //         5
+        //     4      3
+        //   1   2
+        final heap = MinBinaryHeap.buildFromArray([5, 4, 3, 1, 2]);
+        //         1
+        //     2      3
+        //   4   5
+        expect(heap._heap, [1, 2, 3, 4, 5]);
+      });
+    });
   });
 }