Merge branch 'TheAlgorithms:master' into feat/add-tarjan-bridges

Author: Keykyrios

.github/workflows/build.yml

@@ -20,15 +20,15 @@ jobs:
         if: >-
           github.event_name == 'pull_request' &&
           github.event.pull_request.head.repo.full_name != github.repository
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           fail_ci_if_error: true
       - name: Upload coverage to codecov (with token)
         if: >
           github.repository == 'TheAlgorithms/Java' &&
           (github.event_name != 'pull_request' ||
           github.event.pull_request.head.repo.full_name == github.repository)
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true

src/main/java/com/thealgorithms/maths/Volume.java

@@ -125,4 +125,16 @@ public static double volumeFrustumOfPyramid(double upperBaseArea, double lowerBa
     public static double volumeTorus(double majorRadius, double minorRadius) {
         return 2 * Math.PI * Math.PI * majorRadius * minorRadius * minorRadius;
     }
+
+    /**
+     * Calculate the volume of an ellipsoid.
+     *
+     * @param a first semi-axis of an ellipsoid
+     * @param b second semi-axis of an ellipsoid
+     * @param c third semi-axis of an ellipsoid
+     * @return volume of the ellipsoid
+     */
+    public static double volumeEllipsoid(double a, double b, double c) {
+        return (4 * Math.PI * a * b * c) / 3;
+    }
 }

src/main/java/com/thealgorithms/searches/InterpolationSearch.java

@@ -1,3 +1,14 @@
+/**
+ * Interpolation Search estimates the position of the target value
+ * based on the distribution of values.
+ *
+ * Example:
+ * Input: [10, 20, 30, 40], target = 30
+ * Output: Index = 2
+ *
+ * Time Complexity: O(log log n) (average case)
+ * Space Complexity: O(1)
+ */
 package com.thealgorithms.searches;
 
 /**

src/main/java/com/thealgorithms/searches/IterativeBinarySearch.java

@@ -3,50 +3,53 @@
 import com.thealgorithms.devutils.searches.SearchAlgorithm;
 
 /**
- * Binary search is one of the most popular algorithms This class represents
- * iterative version {@link BinarySearch} Iterative binary search is likely to
- * have lower constant factors because it doesn't involve the overhead of
- * manipulating the call stack. But in java the recursive version can be
- * optimized by the compiler to this version.
+ * Binary search is one of the most popular algorithms.
+ * This class represents the iterative version of {@link BinarySearch}.
  *
- * <p>
- * Worst-case performance O(log n) Best-case performance O(1) Average
- * performance O(log n) Worst-case space complexity O(1)
+ * <p>Iterative binary search avoids recursion overhead and uses constant space.
  *
- * @author Gabriele La Greca : https://github.com/thegabriele97
- * @author Podshivalov Nikita (https://github.com/nikitap492)
+ * <p>Performance:
+ * <ul>
+ *   <li>Best-case: O(1)</li>
+ *   <li>Average-case: O(log n)</li>
+ *   <li>Worst-case: O(log n)</li>
+ *   <li>Space complexity: O(1)</li>
+ * </ul>
+ *
+ * @author Gabriele La Greca
+ * @author Podshivalov Nikita
  * @see SearchAlgorithm
  * @see BinarySearch
  */
 public final class IterativeBinarySearch implements SearchAlgorithm {
 
     /**
-     * This method implements an iterative version of binary search algorithm
+     * Performs iterative binary search on a sorted array.
      *
-     * @param array a sorted array
-     * @param key the key to search in array
-     * @return the index of key in the array or -1 if not found
+     * @param array the sorted array
+     * @param key the element to search
+     * @param <T> type of elements (must be Comparable)
+     * @return index of the key if found, otherwise -1
      */
     @Override
     public <T extends Comparable<T>> int find(T[] array, T key) {
-        int l;
-        int r;
-        int k;
-        int cmp;
+        if (array == null || array.length == 0) {
+            return -1;
+        }
 
-        l = 0;
-        r = array.length - 1;
+        int left = 0;
+        int right = array.length - 1;
 
-        while (l <= r) {
-            k = (l + r) >>> 1;
-            cmp = key.compareTo(array[k]);
+        while (left <= right) {
+            int mid = (left + right) >>> 1;
+            int cmp = key.compareTo(array[mid]);
 
             if (cmp == 0) {
-                return k;
+                return mid;
             } else if (cmp < 0) {
-                r = --k;
+                right = mid - 1;
             } else {
-                l = ++k;
+                left = mid + 1;
             }
         }
 

src/main/java/com/thealgorithms/searches/LinearSearch.java

@@ -1,3 +1,16 @@
+/**
+ * Performs Linear Search on an array.
+ *
+ * Linear search checks each element one by one until the target is found
+ * or the array ends.
+ *
+ * Example:
+ * Input: [2, 4, 6, 8], target = 6
+ * Output: Index = 2
+ *
+ * Time Complexity: O(n)
+ * Space Complexity: O(1)
+ */
 package com.thealgorithms.searches;
 
 import com.thealgorithms.devutils.searches.SearchAlgorithm;

src/main/java/com/thealgorithms/stacks/StockSpanProblem.java

@@ -0,0 +1,67 @@
+package com.thealgorithms.stacks;
+
+import java.util.Stack;
+
+/**
+ * Calculates the stock span for each day in a series of stock prices.
+ *
+ * <p>The span of a price on a given day is the number of consecutive days ending on that day
+ * for which the price was less than or equal to the current day's price.
+ *
+ * <p>Idea: keep a stack of indices whose prices are strictly greater than the current price.
+ * While processing each day, pop smaller or equal prices because they are part of the current
+ * span. After popping, the nearest greater price left on the stack tells us where the span stops.
+ *
+ * <p>Time complexity is O(n) because each index is pushed onto the stack once and popped at most
+ * once, so the total number of stack operations grows linearly with the number of prices. This
+ * makes the stack approach efficient because it avoids rechecking earlier days repeatedly, unlike
+ * a naive nested-loop solution that can take O(n^2) time.
+ *
+ * <p>Example: for prices [100, 80, 60, 70, 60, 75, 85], the spans are
+ * [1, 1, 1, 2, 1, 4, 6].
+ */
+public final class StockSpanProblem {
+    private StockSpanProblem() {
+    }
+
+    /**
+     * Calculates the stock span for each price in the input array.
+     *
+     * @param prices the stock prices
+     * @return the span for each day
+     * @throws IllegalArgumentException if the input array is null
+     */
+    public static int[] calculateSpan(int[] prices) {
+        if (prices == null) {
+            throw new IllegalArgumentException("Input prices cannot be null");
+        }
+
+        int[] spans = new int[prices.length];
+        Stack<Integer> stack = new Stack<>();
+
+        // Small example:
+        // prices = [100, 80, 60, 70]
+        // spans  = [  1,  1,  1,  2]
+        // When we process 70, we pop 60 because 60 <= 70, so the span becomes 2.
+        //
+        // The stack stores indices of days with prices greater than the current day's price.
+        for (int index = 0; index < prices.length; index++) {
+            // Remove all previous days whose prices are less than or equal to the current price.
+            while (!stack.isEmpty() && prices[stack.peek()] <= prices[index]) {
+                stack.pop();
+            }
+
+            // If the stack is empty, there is no earlier day with a greater price,
+            // so the count will be from day 0 to this day (index + 1).
+            //
+            // Otherwise, the span is the number of days between
+            // the nearest earlier day with a greater price and the current day.
+            spans[index] = stack.isEmpty() ? index + 1 : index - stack.peek();
+
+            // Store the current index as a candidate for future span calculations.
+            stack.push(index);
+        }
+
+        return spans;
+    }
+}

src/main/java/com/thealgorithms/strings/KasaiAlgorithm.java

@@ -0,0 +1,79 @@
+package com.thealgorithms.strings;
+
+/**
+ * Kasai's Algorithm for constructing the Longest Common Prefix (LCP) array.
+ *
+ * <p>
+ * The LCP array stores the lengths of the longest common prefixes between
+ * lexicographically adjacent suffixes of a string. Kasai's algorithm computes
+ * this array in O(N) time given the string and its suffix array.
+ * </p>
+ *
+ * @see <a href="https://en.wikipedia.org/wiki/LCP_array">LCP array - Wikipedia</a>
+ */
+public final class KasaiAlgorithm {
+
+    private KasaiAlgorithm() {
+    }
+
+    /**
+     * Computes the LCP array using Kasai's algorithm.
+     *
+     * @param text      the original string
+     * @param suffixArr the suffix array of the string
+     * @return the LCP array of length N, where LCP[i] is the length of the longest
+     *         common prefix of the suffixes indexed by suffixArr[i] and suffixArr[i+1].
+     *         The last element LCP[N-1] is always 0.
+     * @throws IllegalArgumentException if text or suffixArr is null, or their lengths differ
+     */
+    public static int[] kasai(String text, int[] suffixArr) {
+        if (text == null || suffixArr == null) {
+            throw new IllegalArgumentException("Text and suffix array must not be null.");
+        }
+        int n = text.length();
+        if (suffixArr.length != n) {
+            throw new IllegalArgumentException("Suffix array length must match text length.");
+        }
+        if (n == 0) {
+            return new int[0];
+        }
+
+        // Compute the inverse suffix array
+        // invSuff[i] stores the index of the suffix text.substring(i) in the suffix array
+        int[] invSuff = new int[n];
+        for (int i = 0; i < n; i++) {
+            if (suffixArr[i] < 0 || suffixArr[i] >= n) {
+                throw new IllegalArgumentException("Suffix array contains out-of-bounds index.");
+            }
+            invSuff[suffixArr[i]] = i;
+        }
+
+        int[] lcp = new int[n];
+        int k = 0; // Length of the longest common prefix
+
+        for (int i = 0; i < n; i++) {
+            // Suffix at index i has not a next suffix in suffix array
+            int rank = invSuff[i];
+            if (rank == n - 1) {
+                k = 0;
+                continue;
+            }
+
+            int nextSuffixIndex = suffixArr[rank + 1];
+
+            // Directly match characters to find LCP
+            while (i + k < n && nextSuffixIndex + k < n && text.charAt(i + k) == text.charAt(nextSuffixIndex + k)) {
+                k++;
+            }
+
+            lcp[rank] = k;
+
+            // Delete the starting character from the string
+            if (k > 0) {
+                k--;
+            }
+        }
+
+        return lcp;
+    }
+}

src/test/java/com/thealgorithms/maths/VolumeTest.java

@@ -41,5 +41,8 @@ public void volume() {
 
         /* test torus */
         assertEquals(39.47841760435743, Volume.volumeTorus(2, 1));
+
+        /* test ellipsoid */
+        assertEquals(25.1327412287183459, Volume.volumeEllipsoid(3, 2, 1));
     }
 }

src/test/java/com/thealgorithms/stacks/StockSpanProblemTest.java

@@ -0,0 +1,34 @@
+package com.thealgorithms.stacks;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.util.stream.Stream;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+
+class StockSpanProblemTest {
+
+    @ParameterizedTest
+    @MethodSource("validTestCases")
+    void testCalculateSpan(int[] prices, int[] expectedSpans) {
+        assertArrayEquals(expectedSpans, StockSpanProblem.calculateSpan(prices));
+    }
+
+    private static Stream<Arguments> validTestCases() {
+        return Stream.of(Arguments.of(new int[] {10, 4, 5, 90, 120, 80}, new int[] {1, 1, 2, 4, 5, 1}), Arguments.of(new int[] {100, 50, 60, 70, 80, 90}, new int[] {1, 1, 2, 3, 4, 5}), Arguments.of(new int[] {5, 4, 3, 2, 1}, new int[] {1, 1, 1, 1, 1}),
+            Arguments.of(new int[] {1, 2, 3, 4, 5}, new int[] {1, 2, 3, 4, 5}), Arguments.of(new int[] {10, 20, 30, 40, 50}, new int[] {1, 2, 3, 4, 5}), Arguments.of(new int[] {100, 80, 60, 70, 60, 75, 85}, new int[] {1, 1, 1, 2, 1, 4, 6}),
+            Arguments.of(new int[] {7, 7, 7, 7}, new int[] {1, 2, 3, 4}), Arguments.of(new int[] {}, new int[] {}), Arguments.of(new int[] {42}, new int[] {1}));
+    }
+
+    @ParameterizedTest
+    @MethodSource("invalidTestCases")
+    void testCalculateSpanInvalidInput(int[] prices) {
+        assertThrows(IllegalArgumentException.class, () -> StockSpanProblem.calculateSpan(prices));
+    }
+
+    private static Stream<Arguments> invalidTestCases() {
+        return Stream.of(Arguments.of((int[]) null));
+    }
+}