refactor: Enhance docs, add tests in GenericHeap

Author: Hardvan

src/main/java/com/thealgorithms/datastructures/heaps/GenericHeap.java

@@ -3,45 +3,86 @@
 import java.util.ArrayList;
 import java.util.HashMap;
 
+/**
+ * A generic implementation of a max heap data structure.
+ *
+ * @param <T> the type of elements in this heap, must extend Comparable.
+ */
 public class GenericHeap<T extends Comparable<T>> {
 
-    ArrayList<T> data = new ArrayList<>();
-    HashMap<T, Integer> map = new HashMap<>();
+    private final ArrayList<T> data = new ArrayList<>();
+    private final HashMap<T, Integer> map = new HashMap<>();
 
+    /**
+     * Adds an item to the heap, maintaining the heap property.
+     *
+     * @param item the item to be added
+     */
     public void add(T item) {
         this.data.add(item);
-        map.put(item, this.data.size() - 1); //
+        map.put(item, this.data.size() - 1);
         upHeapify(this.data.size() - 1);
     }
 
+    /**
+     * Restores the heap property by moving the item at the given index upwards.
+     *
+     * @param ci the index of the current item
+     */
     private void upHeapify(int ci) {
         int pi = (ci - 1) / 2;
-        if (isLarger(this.data.get(ci), this.data.get(pi)) > 0) {
+        if (ci > 0 && isLarger(this.data.get(ci), this.data.get(pi)) > 0) {
             swap(pi, ci);
             upHeapify(pi);
         }
     }
 
+    /**
+     * Displays the contents of the heap.
+     */
     public void display() {
         System.out.println(this.data);
     }
 
+    /**
+     * Returns the number of elements in the heap.
+     *
+     * @return the size of the heap
+     */
     public int size() {
         return this.data.size();
     }
 
+    /**
+     * Checks if the heap is empty.
+     *
+     * @return true if the heap is empty, false otherwise
+     */
     public boolean isEmpty() {
         return this.size() == 0;
     }
 
+    /**
+     * Removes and returns the maximum item from the heap.
+     *
+     * @return the maximum item
+     */
     public T remove() {
+        if (isEmpty()) {
+            throw new IllegalStateException("Heap is empty");
+        }
         this.swap(0, this.size() - 1);
         T rv = this.data.remove(this.size() - 1);
-        downHeapify(0);
         map.remove(rv);
+        downHeapify(0);
         return rv;
     }
 
+    /**
+     * Restores the heap property by moving the item at the given index downwards.
+     *
+     * @param pi the index of the current item
+     */
     private void downHeapify(int pi) {
         int lci = 2 * pi + 1;
         int rci = 2 * pi + 2;
@@ -58,15 +99,35 @@ private void downHeapify(int pi) {
         }
     }
 
+    /**
+     * Retrieves the maximum item from the heap without removing it.
+     *
+     * @return the maximum item
+     */
     public T get() {
-        return this.data.get(0);
+        if (isEmpty()) {
+            throw new IllegalStateException("Heap is empty");
+        }
+        return this.data.getFirst();
     }
 
-    // t has higher property then return +ve
+    /**
+     * Compares two items to determine their order.
+     *
+     * @param t the first item
+     * @param o the second item
+     * @return a positive integer if t is greater than o, negative if t is less, and zero if they are equal
+     */
     private int isLarger(T t, T o) {
         return t.compareTo(o);
     }
 
+    /**
+     * Swaps two items in the heap and updates their indices in the map.
+     *
+     * @param i index of the first item
+     * @param j index of the second item
+     */
     private void swap(int i, int j) {
         T ith = this.data.get(i);
         T jth = this.data.get(j);
@@ -76,9 +137,16 @@ private void swap(int i, int j) {
         map.put(jth, i);
     }
 
+    /**
+     * Updates the priority of the specified item by restoring the heap property.
+     *
+     * @param item the item whose priority is to be updated
+     */
     public void updatePriority(T item) {
+        if (!map.containsKey(item)) {
+            throw new IllegalArgumentException("Item not found in the heap");
+        }
         int index = map.get(item);
-        // because we enter lesser value then old vale
         upHeapify(index);
     }
 }

src/test/java/com/thealgorithms/datastructures/heaps/GenericHeapTest.java

@@ -0,0 +1,93 @@
+package com.thealgorithms.datastructures.heaps;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+class GenericHeapTest {
+
+    private GenericHeap<Integer> heap;
+
+    @BeforeEach
+    void setUp() {
+        heap = new GenericHeap<>();
+    }
+
+    @Test
+    void testAddAndGet() {
+        heap.add(10);
+        heap.add(20);
+        heap.add(5);
+
+        assertEquals(20, heap.get());
+    }
+
+    @Test
+    void testRemove() {
+        heap.add(10);
+        heap.add(20);
+        heap.add(5);
+
+        assertEquals(20, heap.remove());
+        assertEquals(10, heap.get());
+    }
+
+    @Test
+    void testIsEmpty() {
+        assertTrue(heap.isEmpty());
+        heap.add(1);
+        assertFalse(heap.isEmpty());
+    }
+
+    @Test
+    void testSize() {
+        assertEquals(0, heap.size());
+        heap.add(1);
+        heap.add(2);
+        assertEquals(2, heap.size());
+    }
+
+    @Test
+    void testUpdatePriority() {
+        heap.add(10);
+        heap.add(20);
+        heap.add(5);
+
+        heap.updatePriority(10); // This is a no-op since 10 is not greater than 20.
+        assertEquals(20, heap.get());
+
+        heap.add(30);
+        heap.updatePriority(20); // 20 will be moved up
+        assertEquals(30, heap.get());
+    }
+
+    @Test
+    void testRemoveFromEmptyHeap() {
+        Exception exception = assertThrows(IllegalStateException.class, () -> heap.remove());
+        assertEquals("Heap is empty", exception.getMessage());
+    }
+
+    @Test
+    void testGetFromEmptyHeap() {
+        Exception exception = assertThrows(IllegalStateException.class, () -> heap.get());
+        assertEquals("Heap is empty", exception.getMessage());
+    }
+
+    @Test
+    void testUpdatePriorityForNonExistentItem() {
+        Exception exception = assertThrows(IllegalArgumentException.class, () -> heap.updatePriority(100));
+        assertEquals("Item not found in the heap", exception.getMessage());
+    }
+
+    @Test
+    void testDisplay() {
+        heap.add(10);
+        heap.add(20);
+        heap.add(5);
+        heap.display(); // Just checking no exceptions are thrown.
+    }
+}