Merge branch 'master' into master

Author: Anshul-9923

DIRECTORY.md

@@ -871,6 +871,7 @@
               * [LeftistHeapTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/heaps/LeftistHeapTest.java)
               * [MedianFinderTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/heaps/MedianFinderTest.java)
               * [MergeKSortedArraysTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/heaps/MergeKSortedArraysTest.java)
+              * [MinHeapTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/heaps/MinHeapTest.java)
               * [MinPriorityQueueTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/heaps/MinPriorityQueueTest.java)
             * lists
               * [CircleLinkedListTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/CircleLinkedListTest.java)

src/main/java/com/thealgorithms/datastructures/graphs/WelshPowell.java

@@ -5,21 +5,41 @@
 import java.util.HashSet;
 import java.util.stream.IntStream;
 
-/*
- *  The Welsh-Powell algorithm is a graph coloring algorithm
- *  used for coloring a graph with the minimum number of colors.
- *  https://en.wikipedia.org/wiki/Graph_coloring
+/**
+ * The Welsh-Powell algorithm is a graph coloring algorithm that aims to color a graph
+ * using the minimum number of colors such that no two adjacent vertices share the same color.
+ *
+ * <p>
+ * The algorithm works by:
+ * <ol>
+ * <li>Sorting the vertices in descending order based on their degrees (number of edges connected).</li>
+ * <li>Iterating through each vertex and assigning it the smallest available color that has not been used by its adjacent vertices.</li>
+ * <li>Coloring adjacent vertices with the same color is avoided.</li>
+ * </ol>
+ * </p>
+ *
+ * <p>
+ * For more information, see <a href="https://en.wikipedia.org/wiki/Graph_coloring">Graph Coloring</a>.
+ * </p>
  */
-
 public final class WelshPowell {
-    private static final int BLANK_COLOR = -1; // Representing uncolored state
+    private static final int BLANK_COLOR = -1; // Constant representing an uncolored state
 
     private WelshPowell() {
     }
 
+    /**
+     * Represents a graph using an adjacency list.
+     */
     static final class Graph {
-        private HashSet<Integer>[] adjacencyLists;
-
+        private final HashSet<Integer>[] adjacencyLists;
+
+        /**
+         * Initializes a graph with a specified number of vertices.
+         *
+         * @param vertices the number of vertices in the graph
+         * @throws IllegalArgumentException if the number of vertices is negative
+         */
         private Graph(int vertices) {
             if (vertices < 0) {
                 throw new IllegalArgumentException("Number of vertices cannot be negative");
@@ -29,6 +49,13 @@ private Graph(int vertices) {
             Arrays.setAll(adjacencyLists, i -> new HashSet<>());
         }
 
+        /**
+         * Adds an edge between two vertices in the graph.
+         *
+         * @param nodeA one end of the edge
+         * @param nodeB the other end of the edge
+         * @throws IllegalArgumentException if the vertices are out of bounds or if a self-loop is attempted
+         */
         private void addEdge(int nodeA, int nodeB) {
             validateVertex(nodeA);
             validateVertex(nodeB);
@@ -39,21 +66,46 @@ private void addEdge(int nodeA, int nodeB) {
             adjacencyLists[nodeB].add(nodeA);
         }
 
+        /**
+         * Validates that the vertex index is within the bounds of the graph.
+         *
+         * @param vertex the index of the vertex to validate
+         * @throws IllegalArgumentException if the vertex is out of bounds
+         */
         private void validateVertex(int vertex) {
             if (vertex < 0 || vertex >= getNumVertices()) {
                 throw new IllegalArgumentException("Vertex " + vertex + " is out of bounds");
             }
         }
 
+        /**
+         * Returns the adjacency list for a specific vertex.
+         *
+         * @param vertex the index of the vertex
+         * @return the set of adjacent vertices
+         */
         HashSet<Integer> getAdjacencyList(int vertex) {
             return adjacencyLists[vertex];
         }
 
+        /**
+         * Returns the number of vertices in the graph.
+         *
+         * @return the number of vertices
+         */
         int getNumVertices() {
             return adjacencyLists.length;
         }
     }
 
+    /**
+     * Creates a graph with the specified number of vertices and edges.
+     *
+     * @param numberOfVertices the total number of vertices
+     * @param listOfEdges a 2D array representing edges where each inner array contains two vertex indices
+     * @return a Graph object representing the created graph
+     * @throws IllegalArgumentException if the edge array is invalid or vertices are out of bounds
+     */
     public static Graph makeGraph(int numberOfVertices, int[][] listOfEdges) {
         Graph graph = new Graph(numberOfVertices);
         for (int[] edge : listOfEdges) {
@@ -65,6 +117,12 @@ public static Graph makeGraph(int numberOfVertices, int[][] listOfEdges) {
         return graph;
     }
 
+    /**
+     * Finds the coloring of the given graph using the Welsh-Powell algorithm.
+     *
+     * @param graph the input graph to color
+     * @return an array of integers where each index represents a vertex and the value represents the color assigned
+     */
     public static int[] findColoring(Graph graph) {
         int[] colors = initializeColors(graph.getNumVertices());
         Integer[] sortedVertices = getSortedNodes(graph);
@@ -83,30 +141,70 @@ public static int[] findColoring(Graph graph) {
         return colors;
     }
 
+    /**
+     * Helper method to check if a color is unassigned
+     *
+     * @param color the color to check
+     * @return {@code true} if the color is unassigned, {@code false} otherwise
+     */
     private static boolean isBlank(int color) {
         return color == BLANK_COLOR;
     }
 
+    /**
+     * Checks if a vertex has adjacent colored vertices
+     *
+     * @param graph the input graph
+     * @param vertex the vertex to check
+     * @param colors the array of colors assigned to the vertices
+     * @return {@code true} if the vertex has adjacent colored vertices, {@code false} otherwise
+     */
     private static boolean isAdjacentToColored(Graph graph, int vertex, int[] colors) {
         return graph.getAdjacencyList(vertex).stream().anyMatch(otherVertex -> !isBlank(colors[otherVertex]));
     }
 
+    /**
+     * Initializes the colors array with blank color
+     *
+     * @param numberOfVertices the number of vertices in the graph
+     * @return an array of integers representing the colors assigned to the vertices
+     */
     private static int[] initializeColors(int numberOfVertices) {
         int[] colors = new int[numberOfVertices];
         Arrays.fill(colors, BLANK_COLOR);
         return colors;
     }
 
+    /**
+     * Sorts the vertices by their degree in descending order
+     *
+     * @param graph the input graph
+     * @return an array of integers representing the vertices sorted by degree
+     */
     private static Integer[] getSortedNodes(final Graph graph) {
         return IntStream.range(0, graph.getNumVertices()).boxed().sorted(Comparator.comparingInt(v -> - graph.getAdjacencyList(v).size())).toArray(Integer[] ::new);
     }
 
+    /**
+     * Computes the colors already used by the adjacent vertices
+     *
+     * @param graph the input graph
+     * @param vertex the vertex to check
+     * @param colors the array of colors assigned to the vertices
+     * @return an array of booleans representing the colors used by the adjacent vertices
+     */
     private static boolean[] computeUsedColors(final Graph graph, final int vertex, final int[] colors) {
         boolean[] usedColors = new boolean[graph.getNumVertices()];
         graph.getAdjacencyList(vertex).stream().map(neighbor -> colors[neighbor]).filter(color -> !isBlank(color)).forEach(color -> usedColors[color] = true);
         return usedColors;
     }
 
+    /**
+     * Finds the first unused color
+     *
+     * @param usedColors the array of colors used by the adjacent vertices
+     * @return the first unused color
+     */
     private static int firstUnusedColor(boolean[] usedColors) {
         return IntStream.range(0, usedColors.length).filter(color -> !usedColors[color]).findFirst().getAsInt();
     }

src/main/java/com/thealgorithms/datastructures/hashmap/hashing/GenericHashMapUsingArrayList.java

@@ -3,12 +3,34 @@
 import java.util.ArrayList;
 import java.util.LinkedList;
 
+/**
+ * A generic implementation of a hash map using an array list of linked lists for collision resolution.
+ * This class allows storage of key-value pairs with average-case constant time complexity for insertion,
+ * deletion, and retrieval operations.
+ *
+ * <p>
+ * The hash map uses separate chaining to handle collisions. Each bucket in the hash map is represented
+ * by a linked list that holds nodes containing key-value pairs. When multiple keys hash to the same index,
+ * they are stored in the same linked list.
+ * </p>
+ *
+ * <p>
+ * The hash map automatically resizes itself when the load factor exceeds 0.5. The load factor is defined
+ * as the ratio of the number of entries to the number of buckets. When resizing occurs, all existing entries
+ * are rehashed and inserted into the new buckets.
+ * </p>
+ *
+ * @param <K> the type of keys maintained by this hash map
+ * @param <V> the type of mapped values
+ */
 public class GenericHashMapUsingArrayList<K, V> {
 
-    ArrayList<LinkedList<Node>> buckets;
-    private float lf = 0.5f;
-    private int size;
+    private ArrayList<LinkedList<Node>> buckets; // Array list of buckets (linked lists)
+    private int size; // Number of key-value pairs in the hash map
 
+    /**
+     * Constructs a new empty hash map with an initial capacity of 10 buckets.
+     */
     public GenericHashMapUsingArrayList() {
         buckets = new ArrayList<>();
         for (int i = 0; i < 10; i++) {
@@ -17,6 +39,13 @@ public GenericHashMapUsingArrayList() {
         size = 0;
     }
 
+    /**
+     * Associates the specified value with the specified key in this map.
+     * If the map previously contained a mapping for the key, the old value is replaced.
+     *
+     * @param key the key with which the specified value is to be associated
+     * @param value the value to be associated with the specified key
+     */
     public void put(K key, V value) {
         int hash = Math.abs(key.hashCode() % buckets.size());
         LinkedList<Node> nodes = buckets.get(hash);
@@ -31,25 +60,36 @@ public void put(K key, V value) {
         nodes.add(new Node(key, value));
         size++;
 
-        if ((float) size / buckets.size() > lf) {
+        // Load factor threshold for resizing
+        float loadFactorThreshold = 0.5f;
+        if ((float) size / buckets.size() > loadFactorThreshold) {
             reHash();
         }
     }
 
+    /**
+     * Resizes the hash map by doubling the number of buckets and rehashing existing entries.
+     */
     private void reHash() {
-        ArrayList<LinkedList<Node>> old = buckets;
+        ArrayList<LinkedList<Node>> oldBuckets = buckets;
         buckets = new ArrayList<>();
         size = 0;
-        for (int i = 0; i < old.size() * 2; i++) {
+        for (int i = 0; i < oldBuckets.size() * 2; i++) {
             buckets.add(new LinkedList<>());
         }
-        for (LinkedList<Node> nodes : buckets) {
+        for (LinkedList<Node> nodes : oldBuckets) {
             for (Node node : nodes) {
                 put(node.key, node.val);
             }
         }
     }
 
+    /**
+     * Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.
+     *
+     * @param key the key whose associated value is to be returned
+     * @return the value associated with the specified key, or null if no mapping exists
+     */
     public V get(K key) {
         int hash = Math.abs(key.hashCode() % buckets.size());
         LinkedList<Node> nodes = buckets.get(hash);
@@ -61,6 +101,11 @@ public V get(K key) {
         return null;
     }
 
+    /**
+     * Removes the mapping for the specified key from this map if present.
+     *
+     * @param key the key whose mapping is to be removed from the map
+     */
     public void remove(K key) {
         int hash = Math.abs(key.hashCode() % buckets.size());
         LinkedList<Node> nodes = buckets.get(hash);
@@ -72,18 +117,36 @@ public void remove(K key) {
                 break;
             }
         }
-        nodes.remove(target);
-        size--;
+        if (target != null) {
+            nodes.remove(target);
+            size--;
+        }
     }
 
+    /**
+     * Returns true if this map contains a mapping for the specified key.
+     *
+     * @param key the key whose presence in this map is to be tested
+     * @return true if this map contains a mapping for the specified key
+     */
     public boolean containsKey(K key) {
         return get(key) != null;
     }
 
+    /**
+     * Returns the number of key-value pairs in this map.
+     *
+     * @return the number of key-value pairs
+     */
     public int size() {
         return this.size;
     }
 
+    /**
+     * Returns a string representation of the map, containing all key-value pairs.
+     *
+     * @return a string representation of the map
+     */
     @Override
     public String toString() {
         StringBuilder builder = new StringBuilder();
@@ -96,15 +159,27 @@ public String toString() {
                 builder.append(", ");
             }
         }
+        // Remove trailing comma and space if there are any elements
+        if (builder.length() > 1) {
+            builder.setLength(builder.length() - 2);
+        }
         builder.append("}");
         return builder.toString();
     }
 
+    /**
+     * A private inner class representing a key-value pair (node) in the hash map.
+     */
     private class Node {
-
         K key;
         V val;
 
+        /**
+         * Constructs a new Node with the specified key and value.
+         *
+         * @param key the key of the key-value pair
+         * @param val the value of the key-value pair
+         */
         Node(K key, V val) {
             this.key = key;
             this.val = val;

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

@@ -40,5 +40,5 @@ public interface Heap {
      * @param elementIndex int containing the position in the heap of the
      * element to be deleted.
      */
-    void deleteElement(int elementIndex);
+    void deleteElement(int elementIndex) throws EmptyHeapException;
 }

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

@@ -167,4 +167,8 @@ public int hashCode() {
         result += (additionalInfo != null) ? additionalInfo.hashCode() : 0;
         return result;
     }
+
+    public String getValue() {
+        return additionalInfo.toString();
+    }
 }