Merge branch 'TheAlgorithms:master' into master

Author: Hardvan

DIRECTORY.md

@@ -265,6 +265,7 @@
             * [ActivitySelection](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/greedyalgorithms/ActivitySelection.java)
             * [CoinChange](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/greedyalgorithms/CoinChange.java)
             * [FractionalKnapsack](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/greedyalgorithms/FractionalKnapsack.java)
+            * [GaleShapley](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/greedyalgorithms/GaleShapley.java)
             * [JobSequencing](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/greedyalgorithms/JobSequencing.java)
             * [MinimizingLateness](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/greedyalgorithms/MinimizingLateness.java)
           * io
@@ -749,6 +750,7 @@
             * [ActivitySelectionTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/greedyalgorithms/ActivitySelectionTest.java)
             * [CoinChangeTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/greedyalgorithms/CoinChangeTest.java)
             * [FractionalKnapsackTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/greedyalgorithms/FractionalKnapsackTest.java)
+            * [GaleShapleyTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/greedyalgorithms/GaleShapleyTest.java)
             * [JobSequencingTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/greedyalgorithms/JobSequencingTest.java)
             * [MinimizingLatenessTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/greedyalgorithms/MinimizingLatenessTest.java)
           * io

src/main/java/com/thealgorithms/backtracking/MColoring.java

@@ -7,71 +7,90 @@
 import java.util.Set;
 
 /**
+ * Node class represents a graph node. Each node is associated with a color
+ * (initially 1) and contains a set of edges representing its adjacent nodes.
+ *
  * @author Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
  */
 class Node {
-    int color = 1;
-    Set<Integer> edges = new HashSet<Integer>();
+    int color = 1; // Initial color for each node
+    Set<Integer> edges = new HashSet<Integer>(); // Set of edges representing adjacent nodes
 }
 
+/**
+ * MColoring class solves the M-Coloring problem where the goal is to determine
+ * if it's possible to color a graph using at most M colors such that no two
+ * adjacent nodes have the same color.
+ */
 public final class MColoring {
+
     private MColoring() {
-    }
-    static int possiblePaint(ArrayList<Node> nodes, int n, int m) {
+    } // Prevent instantiation of utility class
 
-        // Create a visited array of n nodes
+    /**
+     * Determines whether it is possible to color the graph using at most M colors.
+     *
+     * @param nodes List of nodes representing the graph.
+     * @param n     The total number of nodes in the graph.
+     * @param m     The maximum number of allowed colors.
+     * @return true if the graph can be colored using M colors, false otherwise.
+     */
+    static boolean isColoringPossible(ArrayList<Node> nodes, int n, int m) {
+
+        // Visited array keeps track of whether each node has been processed.
         ArrayList<Integer> visited = new ArrayList<Integer>();
         for (int i = 0; i < n + 1; i++) {
-            visited.add(0);
+            visited.add(0); // Initialize all nodes as unvisited (0)
         }
 
-        // maxColors used till now are 1 as
-        // all nodes are painted color 1
+        // The number of colors used so far (initially set to 1, since all nodes
+        // start with color 1).
         int maxColors = 1;
 
+        // Loop through all the nodes to ensure every node is visited, in case the
+        // graph is disconnected.
         for (int sv = 1; sv <= n; sv++) {
             if (visited.get(sv) > 0) {
-                continue;
+                continue; // Skip nodes that are already visited
             }
 
-            // If the starting point is unvisited,
-            // mark it visited and push it in queue
+            // If the node is unvisited, mark it as visited and add it to the queue for BFS.
             visited.set(sv, 1);
             Queue<Integer> q = new LinkedList<>();
             q.add(sv);
 
-            // BFS
+            // Perform BFS to process all nodes and their adjacent nodes
             while (q.size() != 0) {
-                int top = q.peek();
+                int top = q.peek(); // Get the current node from the queue
                 q.remove();
 
-                // Checking all adjacent nodes
-                // to "top" edge in our queue
+                // Check all adjacent nodes of the current node
                 for (int it : nodes.get(top).edges) {
 
-                    // If the color of the
-                    // adjacent node is same, increase it by
-                    // 1
+                    // If the adjacent node has the same color as the current node, increment its
+                    // color to avoid conflict.
                     if (nodes.get(top).color == nodes.get(it).color) {
                         nodes.get(it).color += 1;
                     }
 
-                    // If number of colors used exceeds m,
-                    // return 0
+                    // Keep track of the maximum number of colors used so far
                     maxColors = Math.max(maxColors, Math.max(nodes.get(top).color, nodes.get(it).color));
+
+                    // If the number of colors used exceeds the allowed limit M, return false.
                     if (maxColors > m) {
-                        return 0;
+                        return false;
                     }
 
-                    // If the adjacent node is not visited,
-                    // mark it visited and push it in queue
+                    // If the adjacent node hasn't been visited yet, mark it as visited and add it
+                    // to the queue for further processing.
                     if (visited.get(it) == 0) {
                         visited.set(it, 1);
                         q.add(it);
                     }
                 }
             }
         }
-        return 1;
+
+        return true; // Possible to color the entire graph with M or fewer colors.
     }
 }

src/main/java/com/thealgorithms/dynamicprogramming/ClimbingStairs.java

@@ -1,31 +1,55 @@
 package com.thealgorithms.dynamicprogramming;
 
-/* A DynamicProgramming solution for Climbing Stairs' problem Returns the
-    distinct ways can you climb to the staircase by either climbing 1 or 2 steps.
-
-    Link : https://medium.com/analytics-vidhya/leetcode-q70-climbing-stairs-easy-444a4aae54e8
-*/
+/*
+ * A dynamic programming solution for the "Climbing Stairs" problem.
+ * Returns the no. of distinct ways to climb to the top
+ * of a staircase when you can climb either 1 or 2 steps at a time.
+ *
+ * For example, if there are 5 steps, the possible ways to climb the
+ * staircase are:
+ * 1. 1-1-1-1-1
+ * 2. 1-1-1-2
+ * 3. 1-2-1-1
+ * 4. 2-1-1-1
+ * 5. 2-2-1
+ * 6. 1-1-2-1
+ * 7. 1-2-2
+ * 8. 2-1-2
+ * Ans: 8 ways
+ */
 public final class ClimbingStairs {
+
     private ClimbingStairs() {
     }
 
+    /**
+     * Calculates the no. of distinct ways to climb a staircase with n steps.
+     *
+     * @param n the no. of steps in the staircase (non-negative integer)
+     * @return the no. of distinct ways to climb to the top
+     *         - Returns 0 if n is 0 (no steps to climb).
+     *         - Returns 1 if n is 1 (only one way to climb).
+     *         - For n > 1, it returns the total no. of ways to climb.
+     */
     public static int numberOfWays(int n) {
 
+        // Base case: if there are no steps or only one step, return n.
         if (n == 1 || n == 0) {
             return n;
         }
-        int prev = 1;
-        int curr = 1;
 
-        int next;
+        int prev = 1; // Ways to reach the step before the current one (step 1)
+        int curr = 1; // Ways to reach the current step (step 2)
+        int next; // Total ways to reach the next step
 
-        for (int i = 2; i <= n; i++) {
+        for (int i = 2; i <= n; i++) { // step 2 to n
             next = curr + prev;
-            prev = curr;
 
+            // Move the pointers to the next step
+            prev = curr;
             curr = next;
         }
 
-        return curr;
+        return curr; // Ways to reach the nth step
     }
 }

src/main/java/com/thealgorithms/greedyalgorithms/GaleShapley.java

@@ -0,0 +1,65 @@
+package com.thealgorithms.greedyalgorithms;
+
+import java.util.HashMap;
+import java.util.LinkedList;
+import java.util.Map;
+
+/**
+ * Implementation of the Gale-Shapley Algorithm for Stable Matching.
+ * Problem link: https://en.wikipedia.org/wiki/Stable_marriage_problem
+ */
+public final class GaleShapley {
+
+    private GaleShapley() {
+    }
+
+    /**
+     * Function to find stable matches between men and women.
+     *
+     * @param womenPrefs A map containing women's preferences where each key is a woman and the value is an array of men in order of preference.
+     * @param menPrefs   A map containing men's preferences where each key is a man and the value is an array of women in order of preference.
+     * @return A map containing stable matches where the key is a woman and the value is her matched man.
+     */
+    public static Map<String, String> stableMatch(Map<String, LinkedList<String>> womenPrefs, Map<String, LinkedList<String>> menPrefs) {
+        // Initialize all men as free
+        Map<String, String> engagements = new HashMap<>();
+        LinkedList<String> freeMen = new LinkedList<>(menPrefs.keySet());
+
+        // While there are free men
+        while (!freeMen.isEmpty()) {
+            String man = freeMen.poll(); // Get the first free man
+            LinkedList<String> manPref = menPrefs.get(man); // Get the preferences of the man
+
+            // Check if manPref is null or empty
+            if (manPref == null || manPref.isEmpty()) {
+                continue; // Skip if no preferences
+            }
+
+            // Propose to the first woman in the man's preference list
+            String woman = manPref.poll();
+            String fiance = engagements.get(woman);
+
+            // If the woman is not engaged, engage her with the current man
+            if (fiance == null) {
+                engagements.put(woman, man);
+            } else {
+                // If the woman prefers the current man over her current fiance
+                LinkedList<String> womanPrefList = womenPrefs.get(woman);
+
+                // Check if womanPrefList is null
+                if (womanPrefList == null) {
+                    continue; // Skip if no preferences for the woman
+                }
+
+                if (womanPrefList.indexOf(man) < womanPrefList.indexOf(fiance)) {
+                    engagements.put(woman, man);
+                    freeMen.add(fiance); // Previous fiance becomes free
+                } else {
+                    // Woman rejects the new proposal, the man remains free
+                    freeMen.add(man);
+                }
+            }
+        }
+        return engagements; // Return the stable matches
+    }
+}

src/test/java/com/thealgorithms/backtracking/MColoringTest.java

@@ -1,6 +1,7 @@
 package com.thealgorithms.backtracking;
 
-import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import java.util.ArrayList;
 import org.junit.jupiter.api.Test;
@@ -16,7 +17,7 @@ void testGraphColoring1() {
         int[][] graph = {{0, 1, 1, 1}, {1, 0, 1, 0}, {1, 1, 0, 1}, {1, 0, 1, 0}};
         int m = 3; // Number of colors
 
-        assertEquals(1, MColoring.possiblePaint(createGraph(graph), n, m));
+        assertTrue(MColoring.isColoringPossible(createGraph(graph), n, m));
     }
 
     @Test
@@ -25,7 +26,7 @@ void testGraphColoring2() {
         int[][] graph = {{0, 1, 1, 1, 0}, {1, 0, 0, 1, 0}, {1, 0, 0, 1, 1}, {1, 1, 1, 0, 1}, {0, 0, 1, 1, 0}};
         int m = 2; // Number of colors
 
-        assertEquals(0, MColoring.possiblePaint(createGraph(graph), n, m));
+        assertFalse(MColoring.isColoringPossible(createGraph(graph), n, m));
     }
 
     @Test
@@ -34,7 +35,7 @@ void testGraphColoring3() {
         int[][] graph = {{0, 1, 1}, {1, 0, 1}, {1, 1, 0}};
         int m = 2; // Number of colors
 
-        assertEquals(0, MColoring.possiblePaint(createGraph(graph), n, m));
+        assertFalse(MColoring.isColoringPossible(createGraph(graph), n, m));
     }
 
     private ArrayList<Node> createGraph(int[][] graph) {

src/test/java/com/thealgorithms/greedyalgorithms/GaleShapleyTest.java

@@ -0,0 +1,72 @@
+package com.thealgorithms.greedyalgorithms;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.util.HashMap;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+public class GaleShapleyTest {
+
+    @Test
+    public void testStableMatch() {
+        Map<String, LinkedList<String>> womenPrefs = new HashMap<>();
+        womenPrefs.put("A", new LinkedList<>(List.of("X", "Y", "Z")));
+        womenPrefs.put("B", new LinkedList<>(List.of("Y", "X", "Z")));
+        womenPrefs.put("C", new LinkedList<>(List.of("X", "Y", "Z")));
+
+        Map<String, LinkedList<String>> menPrefs = new HashMap<>();
+        menPrefs.put("X", new LinkedList<>(List.of("A", "B", "C")));
+        menPrefs.put("Y", new LinkedList<>(List.of("B", "A", "C")));
+        menPrefs.put("Z", new LinkedList<>(List.of("A", "B", "C")));
+
+        Map<String, String> result = GaleShapley.stableMatch(womenPrefs, menPrefs);
+
+        Map<String, String> expected = new HashMap<>();
+        expected.put("A", "X");
+        expected.put("B", "Y");
+        expected.put("C", "Z");
+
+        assertEquals(expected, result);
+    }
+
+    @Test
+    public void testSinglePair() {
+        Map<String, LinkedList<String>> womenPrefs = new HashMap<>();
+        womenPrefs.put("A", new LinkedList<>(List.of("X")));
+
+        Map<String, LinkedList<String>> menPrefs = new HashMap<>();
+        menPrefs.put("X", new LinkedList<>(List.of("A")));
+
+        Map<String, String> result = GaleShapley.stableMatch(womenPrefs, menPrefs);
+
+        Map<String, String> expected = new HashMap<>();
+        expected.put("A", "X");
+
+        assertEquals(expected, result);
+    }
+
+    @Test
+    public void testEqualPreferences() {
+        Map<String, LinkedList<String>> womenPrefs = new HashMap<>();
+        womenPrefs.put("A", new LinkedList<>(List.of("X", "Y", "Z")));
+        womenPrefs.put("B", new LinkedList<>(List.of("X", "Y", "Z")));
+        womenPrefs.put("C", new LinkedList<>(List.of("X", "Y", "Z")));
+
+        Map<String, LinkedList<String>> menPrefs = new HashMap<>();
+        menPrefs.put("X", new LinkedList<>(List.of("A", "B", "C")));
+        menPrefs.put("Y", new LinkedList<>(List.of("A", "B", "C")));
+        menPrefs.put("Z", new LinkedList<>(List.of("A", "B", "C")));
+
+        Map<String, String> result = GaleShapley.stableMatch(womenPrefs, menPrefs);
+
+        Map<String, String> expected = new HashMap<>();
+        expected.put("A", "X");
+        expected.put("B", "Y");
+        expected.put("C", "Z");
+
+        assertEquals(expected, result);
+    }
+}