Merge branch 'master' into krishnamurthy-improve

DenizAltunkapan · web-flow · commit 77b63693af3a · 2025-10-12T22:00:55.000+02:00
diff --git a/src/main/java/com/thealgorithms/datastructures/graphs/DialsAlgorithm.java b/src/main/java/com/thealgorithms/datastructures/graphs/DialsAlgorithm.java
@@ -0,0 +1,114 @@
+package com.thealgorithms.datastructures.graphs;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * An implementation of Dial's Algorithm for the single-source shortest path problem.
+ * This algorithm is an optimization of Dijkstra's algorithm and is particularly
+ * efficient for graphs with small, non-negative integer edge weights.
+ *
+ * It uses a bucket queue (implemented here as a List of HashSets) to store vertices,
+ * where each bucket corresponds to a specific distance from the source. This is more
+ * efficient than a standard priority queue when the range of edge weights is small.
+ *
+ * Time Complexity: O(E + W * V), where E is the number of edges, V is the number
+ * of vertices, and W is the maximum weight of any edge.
+ *
+ * @see <a href="https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm#Dial's_algorithm">Wikipedia - Dial's Algorithm</a>
+ */
+public final class DialsAlgorithm {
+    /**
+     * Private constructor to prevent instantiation of this utility class.
+     */
+    private DialsAlgorithm() {
+    }
+    /**
+     * Represents an edge in the graph, connecting to a destination vertex with a given weight.
+     */
+    public static class Edge {
+        private final int destination;
+        private final int weight;
+
+        public Edge(int destination, int weight) {
+            this.destination = destination;
+            this.weight = weight;
+        }
+
+        public int getDestination() {
+            return destination;
+        }
+
+        public int getWeight() {
+            return weight;
+        }
+    }
+    /**
+     * Finds the shortest paths from a source vertex to all other vertices in a weighted graph.
+     *
+     * @param graph The graph represented as an adjacency list.
+     * @param source The source vertex to start from (0-indexed).
+     * @param maxEdgeWeight The maximum weight of any single edge in the graph.
+     * @return An array of integers where the value at each index `i` is the
+     * shortest distance from the source to vertex `i`. Unreachable vertices
+     * will have a value of Integer.MAX_VALUE.
+     * @throws IllegalArgumentException if the source vertex is out of bounds.
+     */
+    public static int[] run(List<List<Edge>> graph, int source, int maxEdgeWeight) {
+        int numVertices = graph.size();
+        if (source < 0 || source >= numVertices) {
+            throw new IllegalArgumentException("Source vertex is out of bounds.");
+        }
+
+        // Initialize distances array
+        int[] distances = new int[numVertices];
+        Arrays.fill(distances, Integer.MAX_VALUE);
+        distances[source] = 0;
+
+        // The bucket queue. Size is determined by the max possible path length.
+        int maxPathWeight = maxEdgeWeight * (numVertices > 0 ? numVertices - 1 : 0);
+        List<Set<Integer>> buckets = new ArrayList<>(maxPathWeight + 1);
+        for (int i = 0; i <= maxPathWeight; i++) {
+            buckets.add(new HashSet<>());
+        }
+
+        // Add the source vertex to the first bucket
+        buckets.get(0).add(source);
+
+        // Process buckets in increasing order of distance
+        for (int d = 0; d <= maxPathWeight; d++) {
+            // Process all vertices in the current bucket
+            while (!buckets.get(d).isEmpty()) {
+                // Get and remove a vertex from the current bucket
+                int u = buckets.get(d).iterator().next();
+                buckets.get(d).remove(u);
+
+                // If we've found a shorter path already, skip
+                if (d > distances[u]) {
+                    continue;
+                }
+
+                // Relax all adjacent edges
+                for (Edge edge : graph.get(u)) {
+                    int v = edge.getDestination();
+                    int weight = edge.getWeight();
+
+                    // If a shorter path to v is found
+                    if (distances[u] != Integer.MAX_VALUE && distances[u] + weight < distances[v]) {
+                        // If v was already in a bucket, remove it from the old one
+                        if (distances[v] != Integer.MAX_VALUE) {
+                            buckets.get(distances[v]).remove(v);
+                        }
+                        // Update distance and move v to the new bucket
+                        distances[v] = distances[u] + weight;
+                        buckets.get(distances[v]).add(v);
+                    }
+                }
+            }
+        }
+        return distances;
+    }
+}
diff --git a/src/main/java/com/thealgorithms/others/LowestBasePalindrome.java b/src/main/java/com/thealgorithms/others/LowestBasePalindrome.java
@@ -4,8 +4,26 @@
 import java.util.List;
 
 /**
- * @brief Class for finding the lowest base in which a given integer is a palindrome.
-     cf. https://oeis.org/A016026
+ * Utility class for finding the lowest base in which a given integer is a
+ * palindrome.
+ * <p>
+ * A number is a palindrome in a given base if its representation in that base
+ * reads the same
+ * forwards and backwards. For example, 15 in base 2 is 1111, which is
+ * palindromic.
+ * This class provides methods to check palindromic properties and find the
+ * smallest base
+ * where a number becomes palindromic.
+ * </p>
+ * <p>
+ * Example: The number 15 in base 2 is represented as [1,1,1,1], which is
+ * palindromic.
+ * The number 10 in base 3 is represented as [1,0,1], which is also palindromic.
+ * </p>
+ *
+ * @see <a href="https://oeis.org/A016026">OEIS A016026 - Smallest base in which
+ *      n is palindromic</a>
+ * @author TheAlgorithms Contributors
  */
 public final class LowestBasePalindrome {
     private LowestBasePalindrome() {
@@ -37,12 +55,18 @@ private static void checkNumber(int number) {
 
     /**
      * Computes the digits of a given number in a specified base.
+     * <p>
+     * The digits are returned in reverse order (least significant digit first).
+     * For example, the number 13 in base 2 produces [1,0,1,1] representing 1101 in
+     * binary.
+     * </p>
      *
-     * @param number the number to be converted
-     * @param base the base to be used for the conversion
-     * @return a list of digits representing the number in the given base, with the most
-     *         significant digit at the end of the list
-     * @throws IllegalArgumentException if the number is negative or the base is less than 2
+     * @param number the number to be converted (must be non-negative)
+     * @param base   the base to be used for the conversion (must be greater than 1)
+     * @return a list of digits representing the number in the given base, with the
+     *         least significant digit at the beginning of the list
+     * @throws IllegalArgumentException if the number is negative or the base is
+     *                                  less than 2
      */
     public static List<Integer> computeDigitsInBase(int number, int base) {
         checkNumber(number);
@@ -58,6 +82,10 @@ public static List<Integer> computeDigitsInBase(int number, int base) {
 
     /**
      * Checks if a list of integers is palindromic.
+     * <p>
+     * A list is palindromic if it reads the same forwards and backwards.
+     * For example, [1,2,1] is palindromic, but [1,2,3] is not.
+     * </p>
      *
      * @param list the list of integers to be checked
      * @return {@code true} if the list is a palindrome, {@code false} otherwise
@@ -73,12 +101,29 @@ public static boolean isPalindromic(List<Integer> list) {
     }
 
     /**
-     * Checks if the representation of a given number in a specified base is palindromic.
+     * Checks if the representation of a given number in a specified base is
+     * palindromic.
+     * <p>
+     * This method first validates the input, then applies optimization: if the
+     * number
+     * ends with 0 in the given base (i.e., divisible by the base), it cannot be
+     * palindromic
+     * as palindromes cannot start with 0.
+     * </p>
+     * <p>
+     * Examples:
+     * - 101 in base 10 is palindromic (101)
+     * - 15 in base 2 is palindromic (1111)
+     * - 10 in base 3 is palindromic (101)
+     * </p>
      *
-     * @param number the number to be checked
-     * @param base the base in which the number will be represented
-     * @return {@code true} if the number is palindromic in the specified base, {@code false} otherwise
-     * @throws IllegalArgumentException if the number is negative or the base is less than 2
+     * @param number the number to be checked (must be non-negative)
+     * @param base   the base in which the number will be represented (must be
+     *               greater than 1)
+     * @return {@code true} if the number is palindromic in the specified base,
+     *         {@code false} otherwise
+     * @throws IllegalArgumentException if the number is negative or the base is
+     *                                  less than 2
      */
     public static boolean isPalindromicInBase(int number, int base) {
         checkNumber(number);
@@ -89,18 +134,38 @@ public static boolean isPalindromicInBase(int number, int base) {
         }
 
         if (number % base == 0) {
-            // If the last digit of the number in the given base is 0, it can't be palindromic
+            // If the last digit of the number in the given base is 0, it can't be
+            // palindromic
             return false;
         }
 
         return isPalindromic(computeDigitsInBase(number, base));
     }
 
     /**
-     * Finds the smallest base in which the representation of a given number is palindromic.
+     * Finds the smallest base in which the representation of a given number is
+     * palindromic.
+     * <p>
+     * This method iteratively checks bases starting from 2 until it finds one where
+     * the number is palindromic. For any number n ≥ 2, the number is always
+     * palindromic
+     * in base n-1 (represented as [1, 1]), so this algorithm is guaranteed to
+     * terminate.
+     * </p>
+     * <p>
+     * Time Complexity: O(n * log(n)) in the worst case, where we check each base
+     * and
+     * convert the number to that base.
+     * </p>
+     * <p>
+     * Examples:
+     * - lowestBasePalindrome(15) returns 2 (15 in base 2 is 1111)
+     * - lowestBasePalindrome(10) returns 3 (10 in base 3 is 101)
+     * - lowestBasePalindrome(11) returns 10 (11 in base 10 is 11)
+     * </p>
      *
-     * @param number the number to be checked
-     * @return the smallest base in which the number is a palindrome
+     * @param number the number to be checked (must be non-negative)
+     * @return the smallest base in which the number is a palindrome (base ≥ 2)
      * @throws IllegalArgumentException if the number is negative
      */
     public static int lowestBasePalindrome(int number) {
diff --git a/src/test/java/com/thealgorithms/datastructures/graphs/DialsAlgorithmTest.java b/src/test/java/com/thealgorithms/datastructures/graphs/DialsAlgorithmTest.java
@@ -0,0 +1,88 @@
+package com.thealgorithms.datastructures.graphs;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.util.ArrayList;
+import java.util.List;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+final class DialsAlgorithmTest {
+
+    private List<List<DialsAlgorithm.Edge>> graph;
+    private static final int NUM_VERTICES = 6;
+    private static final int MAX_EDGE_WEIGHT = 10;
+
+    @BeforeEach
+    void setUp() {
+        graph = new ArrayList<>();
+        for (int i = 0; i < NUM_VERTICES; i++) {
+            graph.add(new ArrayList<>());
+        }
+    }
+
+    private void addEdge(int u, int v, int weight) {
+        graph.get(u).add(new DialsAlgorithm.Edge(v, weight));
+    }
+
+    @Test
+    @DisplayName("Test with a simple connected graph")
+    void testSimpleGraph() {
+        // Build graph from a standard example
+        addEdge(0, 1, 2);
+        addEdge(0, 2, 4);
+        addEdge(1, 2, 1);
+        addEdge(1, 3, 7);
+        addEdge(2, 4, 3);
+        addEdge(3, 5, 1);
+        addEdge(4, 3, 2);
+        addEdge(4, 5, 5);
+
+        int[] expectedDistances = {0, 2, 3, 8, 6, 9};
+        int[] actualDistances = DialsAlgorithm.run(graph, 0, MAX_EDGE_WEIGHT);
+        assertArrayEquals(expectedDistances, actualDistances);
+    }
+
+    @Test
+    @DisplayName("Test with a disconnected node")
+    void testDisconnectedNode() {
+        addEdge(0, 1, 5);
+        addEdge(1, 2, 5);
+        // Node 3, 4, 5 are disconnected
+
+        int[] expectedDistances = {0, 5, 10, Integer.MAX_VALUE, Integer.MAX_VALUE, Integer.MAX_VALUE};
+        int[] actualDistances = DialsAlgorithm.run(graph, 0, MAX_EDGE_WEIGHT);
+        assertArrayEquals(expectedDistances, actualDistances);
+    }
+
+    @Test
+    @DisplayName("Test with source as destination")
+    void testSourceIsDestination() {
+        addEdge(0, 1, 10);
+        int[] expectedDistances = {0, 10, Integer.MAX_VALUE, Integer.MAX_VALUE, Integer.MAX_VALUE, Integer.MAX_VALUE};
+        // Run with source 0
+        int[] actualDistances = DialsAlgorithm.run(graph, 0, MAX_EDGE_WEIGHT);
+        assertArrayEquals(expectedDistances, actualDistances);
+    }
+
+    @Test
+    @DisplayName("Test graph with multiple paths to a node")
+    void testMultiplePaths() {
+        addEdge(0, 1, 10);
+        addEdge(0, 2, 3);
+        addEdge(2, 1, 2); // Shorter path to 1 is via 2 (3+2=5)
+
+        int[] expectedDistances = {0, 5, 3, Integer.MAX_VALUE, Integer.MAX_VALUE, Integer.MAX_VALUE};
+        int[] actualDistances = DialsAlgorithm.run(graph, 0, MAX_EDGE_WEIGHT);
+        assertArrayEquals(expectedDistances, actualDistances);
+    }
+
+    @Test
+    @DisplayName("Test with an invalid source vertex")
+    void testInvalidSource() {
+        assertThrows(IllegalArgumentException.class, () -> DialsAlgorithm.run(graph, -1, MAX_EDGE_WEIGHT));
+        assertThrows(IllegalArgumentException.class, () -> DialsAlgorithm.run(graph, NUM_VERTICES, MAX_EDGE_WEIGHT));
+    }
+}
diff --git a/src/test/java/com/thealgorithms/others/LowestBasePalindromeTest.java b/src/test/java/com/thealgorithms/others/LowestBasePalindromeTest.java
