dsa-ruby 1.0.0 → 1.0.2

data/lib/dsa-ruby/heap.rb

@@ -1,145 +1,273 @@
-module DSA
-  class MinHeap
-    def initialize(elements = [])
-      @elements = []
-      elements.each { |e| push(e) }
-    end
+# DSA::MinHeap - A min-heap (priority queue) data structure.
+#
+# The smallest element is always at the root. Provides O(log n) insertion
+# and extraction of the minimum element.
+#
+# @example
+#   heap = DSA::MinHeap.new([5, 3, 7, 1])
+#   heap.pop   # => 1
+#   heap.peek  # => 3
+#
+#   # Or build incrementally with chained pushes:
+#   heap = DSA::MinHeap.new
+#   heap.push(5).push(3).push(7).push(1)
+class DSA::MinHeap
+  # Initialize a new min-heap with optional initial elements.
+  #
+  # @param elements [Array<Comparable>] optional array of elements to heapify
+  # @return [DSA::MinHeap] a new min-heap
+  # @example
+  #   DSA::MinHeap.new([3, 1, 2])
+  def initialize(elements = [])
+    @elements = []
+    elements.each { |e| push(e) }
+  end
 
-    def push(val)
-      @elements << val
-      sift_up(@elements.size - 1)
-      self
-    end
+  # Inserts an element into the heap.
+  #
+  # @param val [Comparable] the value to insert
+  # @return [DSA::MinHeap] self for method chaining
+  # @example
+  #   heap.push(5).push(3).push(1)
+  def push(val)
+    @elements << val
+    sift_up(@elements.size - 1)
+    self
+  end
 
-    def pop
-      raise IndexError, "heap is empty" if empty?
+  # Removes and returns the minimum element from the heap.
+  #
+  # @return [Comparable] the minimum element
+  # @raise [IndexError] if the heap is empty
+  # @example
+  #   heap.push(5).push(1).push(3)
+  #   heap.pop  # => 1
+  def pop
+    raise IndexError, "heap is empty" if empty?
 
-      swap(0, @elements.size - 1)
-      min = @elements.pop
-      sift_down(0)
-      min
-    end
+    swap(0, @elements.size - 1)
+    min = @elements.pop
+    sift_down(0)
+    min
+  end
 
-    def peek
-      raise IndexError, "heap is empty" if empty?
-      @elements[0]
-    end
+  # Returns the minimum element without removing it.
+  #
+  # @return [Comparable] the minimum element
+  # @raise [IndexError] if the heap is empty
+  # @example
+  #   heap.push(5).push(1).push(3)
+  #   heap.peek  # => 1
+  def peek
+    raise IndexError, "heap is empty" if empty?
+    @elements[0]
+  end
 
-    def size
-      @elements.size
-    end
+  # Returns the number of elements in the heap.
+  #
+  # @return [Integer] the number of elements
+  # @example
+  #   heap.push(5).push(3)
+  #   heap.size  # => 2
+  def size
+    @elements.size
+  end
 
-    def empty?
-      @elements.empty?
-    end
+  # Checks if the heap is empty.
+  #
+  # @return [Boolean] true if the heap contains no elements
+  # @example
+  #   heap = DSA::MinHeap.new
+  #   heap.empty?  # => true
+  def empty?
+    @elements.empty?
+  end
 
-    def to_a
-      @elements.dup
-    end
+  # Returns a defensive copy of the heap as an array.
+  #
+  # @return [Array<Comparable>] an array containing all elements (not in sorted order)
+  # @example
+  #   heap.push(5).push(3).push(1)
+  #   heap.to_a  # => [1, 3, 5] (may vary based on internal structure)
+  def to_a
+    @elements.dup
+  end
 
-    private
+  private
 
-    def sift_up(i)
-      while i > 0
-        parent = (i - 1) / 2
-        break if (@elements[parent] <=> @elements[i]) <= 0
+  # Moves an element up the heap to restore the heap property.
+  #
+  # @param i [Integer] the index of the element to sift up
+  def sift_up(i)
+    while i > 0
+      parent = (i - 1) / 2
+      break if (@elements[parent] <=> @elements[i]) <= 0
 
-        swap(parent, i)
-        i = parent
-      end
+      swap(parent, i)
+      i = parent
     end
+  end
 
-    def sift_down(i)
-      n = @elements.size
-      loop do
-        smallest = i
-        left = 2 * i + 1
-        right = 2 * i + 2
+  # Moves an element down the heap to restore the heap property.
+  #
+  # @param i [Integer] the index of the element to sift down
+  def sift_down(i)
+    n = @elements.size
+    loop do
+      smallest = i
+      left = 2 * i + 1
+      right = 2 * i + 2
 
-        smallest = left if left < n && (@elements[left] <=> @elements[smallest]) < 0
-        smallest = right if right < n && (@elements[right] <=> @elements[smallest]) < 0
+      smallest = left if left < n && (@elements[left] <=> @elements[smallest]) < 0
+      smallest = right if right < n && (@elements[right] <=> @elements[smallest]) < 0
 
-        break if smallest == i
+      break if smallest == i
 
-        swap(i, smallest)
-        i = smallest
-      end
+      swap(i, smallest)
+      i = smallest
     end
+  end
 
-    def swap(i, j)
-      @elements[i], @elements[j] = @elements[j], @elements[i]
-    end
+  # Swaps two elements in the heap array.
+  #
+  # @param i [Integer] index of first element
+  # @param j [Integer] index of second element
+  def swap(i, j)
+    @elements[i], @elements[j] = @elements[j], @elements[i]
   end
+end
 
-  class MaxHeap
-    def initialize(elements = [])
-      @elements = []
-      elements.each { |e| push(e) }
-    end
+# DSA::MaxHeap - A max-heap (priority queue) data structure.
+#
+# The largest element is always at the root. Provides O(log n) insertion
+# and extraction of the maximum element.
+#
+# @example
+#   heap = DSA::MaxHeap.new([5, 3, 7, 1])
+#   heap.pop   # => 7
+#   heap.peek  # => 5
+class DSA::MaxHeap
+  # Initialize a new max-heap with optional initial elements.
+  #
+  # @param elements [Array<Comparable>] optional array of elements to heapify
+  # @return [DSA::MaxHeap] a new max-heap
+  # @example
+  #   DSA::MaxHeap.new([3, 1, 2])
+  def initialize(elements = [])
+    @elements = []
+    elements.each { |e| push(e) }
+  end
 
-    def push(val)
-      @elements << val
-      sift_up(@elements.size - 1)
-      self
-    end
+  # Inserts an element into the heap.
+  #
+  # @param val [Comparable] the value to insert
+  # @return [DSA::MaxHeap] self for method chaining
+  # @example
+  #   heap.push(5).push(3).push(1)
+  def push(val)
+    @elements << val
+    sift_up(@elements.size - 1)
+    self
+  end
 
-    def pop
-      raise IndexError, "heap is empty" if empty?
+  # Removes and returns the maximum element from the heap.
+  #
+  # @return [Comparable] the maximum element
+  # @raise [IndexError] if the heap is empty
+  # @example
+  #   heap.push(5).push(1).push(3)
+  #   heap.pop  # => 5
+  def pop
+    raise IndexError, "heap is empty" if empty?
 
-      swap(0, @elements.size - 1)
-      max = @elements.pop
-      sift_down(0)
-      max
-    end
+    swap(0, @elements.size - 1)
+    max = @elements.pop
+    sift_down(0)
+    max
+  end
 
-    def peek
-      raise IndexError, "heap is empty" if empty?
-      @elements[0]
-    end
+  # Returns the maximum element without removing it.
+  #
+  # @return [Comparable] the maximum element
+  # @raise [IndexError] if the heap is empty
+  # @example
+  #   heap.push(5).push(1).push(3)
+  #   heap.peek  # => 5
+  def peek
+    raise IndexError, "heap is empty" if empty?
+    @elements[0]
+  end
 
-    def size
-      @elements.size
-    end
+  # Returns the number of elements in the heap.
+  #
+  # @return [Integer] the number of elements
+  # @example
+  #   heap.push(5).push(3)
+  #   heap.size  # => 2
+  def size
+    @elements.size
+  end
 
-    def empty?
-      @elements.empty?
-    end
+  # Checks if the heap is empty.
+  #
+  # @return [Boolean] true if the heap contains no elements
+  # @example
+  #   heap = DSA::MaxHeap.new
+  #   heap.empty?  # => true
+  def empty?
+    @elements.empty?
+  end
 
-    def to_a
-      @elements.dup
-    end
+  # Returns a defensive copy of the heap as an array.
+  #
+  # @return [Array<Comparable>] an array containing all elements (not in sorted order)
+  # @example
+  #   heap.push(5).push(3).push(1)
+  #   heap.to_a  # => [5, 3, 1] (may vary based on internal structure)
+  def to_a
+    @elements.dup
+  end
 
-    private
+  private
 
-    def sift_up(i)
-      while i > 0
-        parent = (i - 1) / 2
-        break if (@elements[parent] <=> @elements[i]) >= 0
+  # Moves an element up the heap to restore the heap property.
+  #
+  # @param i [Integer] the index of the element to sift up
+  def sift_up(i)
+    while i > 0
+      parent = (i - 1) / 2
+      break if (@elements[parent] <=> @elements[i]) >= 0
 
-        swap(parent, i)
-        i = parent
-      end
+      swap(parent, i)
+      i = parent
     end
+  end
 
-    def sift_down(i)
-      n = @elements.size
-      loop do
-        largest = i
-        left = 2 * i + 1
-        right = 2 * i + 2
+  # Moves an element down the heap to restore the heap property.
+  #
+  # @param i [Integer] the index of the element to sift down
+  def sift_down(i)
+    n = @elements.size
+    loop do
+      largest = i
+      left = 2 * i + 1
+      right = 2 * i + 2
 
-        largest = left if left < n && (@elements[left] <=> @elements[largest]) > 0
-        largest = right if right < n && (@elements[right] <=> @elements[largest]) > 0
+      largest = left if left < n && (@elements[left] <=> @elements[largest]) > 0
+      largest = right if right < n && (@elements[right] <=> @elements[largest]) > 0
 
-        break if largest == i
+      break if largest == i
 
-        swap(i, largest)
-        i = largest
-      end
+      swap(i, largest)
+      i = largest
     end
+  end
 
-    def swap(i, j)
-      @elements[i], @elements[j] = @elements[j], @elements[i]
-    end
+  # Swaps two elements in the heap array.
+  #
+  # @param i [Integer] index of first element
+  # @param j [Integer] index of second element
+  def swap(i, j)
+    @elements[i], @elements[j] = @elements[j], @elements[i]
   end
 end