Merge branch 'master' into SMJI/stack/min_max_const_time

Author: S-M-J-I

DIRECTORY.md

@@ -607,13 +607,15 @@
             * [WiggleSort](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/sorts/WiggleSort.java)
           * stacks
             * [BalancedBrackets](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/BalancedBrackets.java)
+            * [CelebrityFinder](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/CelebrityFinder.java)
             * [DecimalToAnyUsingStack](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/DecimalToAnyUsingStack.java)
             * [DuplicateBrackets](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/DuplicateBrackets.java)
             * [InfixToPostfix](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/InfixToPostfix.java)
             * [InfixToPrefix](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/InfixToPrefix.java)
             * [LargestRectangle](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/LargestRectangle.java)
             * [MaximumMinimumWindow](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/MaximumMinimumWindow.java)
             * [MinStackUsingSingleStack](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/MinStackUsingSingleStack.java)
+            * [MinStackUsingTwoStacks](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/MinStackUsingTwoStacks.java)
             * [NextGreaterElement](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/NextGreaterElement.java)
             * [NextSmallerElement](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/NextSmallerElement.java)
             * [PostfixEvaluator](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/stacks/PostfixEvaluator.java)
@@ -1162,12 +1164,14 @@
             * [WiggleSortTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/sorts/WiggleSortTest.java)
           * stacks
             * [BalancedBracketsTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/stacks/BalancedBracketsTest.java)
+            * [CelebrityFinderTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/stacks/CelebrityFinderTest.java)
             * [DecimalToAnyUsingStackTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/stacks/DecimalToAnyUsingStackTest.java)
             * [DuplicateBracketsTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/stacks/DuplicateBracketsTest.java)
             * [InfixToPostfixTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/stacks/InfixToPostfixTest.java)
             * [InfixToPrefixTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/stacks/InfixToPrefixTest.java)
             * [LargestRectangleTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/stacks/LargestRectangleTest.java)
             * [MinStackUsingSingleStackTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/stacks/MinStackUsingSingleStackTest.java)
+            * [MinStackUsingTwoStacksTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/stacks/MinStackUsingTwoStacksTest.java)
             * [NextGreaterElementTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/stacks/NextGreaterElementTest.java)
             * [NextSmallerElementTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/stacks/NextSmallerElementTest.java)
             * [PostfixEvaluatorTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/stacks/PostfixEvaluatorTest.java)

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

@@ -4,32 +4,44 @@
 import java.util.List;
 
 /**
- * Finds all combinations of 0...n-1 of length k
+ * This class provides methods to find all combinations of integers from 0 to n-1
+ * of a specified length k using backtracking.
  */
 public final class ArrayCombination {
     private ArrayCombination() {
     }
 
     /**
-     * Finds all combinations of length k of 0..n-1 using backtracking.
+     * Generates all possible combinations of length k from the integers 0 to n-1.
      *
-     * @param n Number of the elements.
-     * @param k Length of the combination.
-     * @return A list of all combinations of length k.
+     * @param n The total number of elements (0 to n-1).
+     * @param k The desired length of each combination.
+     * @return A list containing all combinations of length k.
+     * @throws IllegalArgumentException if n or k are negative, or if k is greater than n.
      */
     public static List<List<Integer>> combination(int n, int k) {
         if (n < 0 || k < 0 || k > n) {
-            throw new IllegalArgumentException("Wrong input.");
+            throw new IllegalArgumentException("Invalid input: n must be non-negative, k must be non-negative and less than or equal to n.");
         }
 
         List<List<Integer>> combinations = new ArrayList<>();
         combine(combinations, new ArrayList<>(), 0, n, k);
         return combinations;
     }
 
+    /**
+     * A helper method that uses backtracking to find combinations.
+     *
+     * @param combinations The list to store all valid combinations found.
+     * @param current The current combination being built.
+     * @param start The starting index for the current recursion.
+     * @param n The total number of elements (0 to n-1).
+     * @param k The desired length of each combination.
+     */
     private static void combine(List<List<Integer>> combinations, List<Integer> current, int start, int n, int k) {
-        if (current.size() == k) { // Base case: combination found
-            combinations.add(new ArrayList<>(current)); // Copy to avoid modification
+        // Base case: combination found
+        if (current.size() == k) {
+            combinations.add(new ArrayList<>(current));
             return;
         }
 

src/main/java/com/thealgorithms/geometry/BresenhamLine.java

@@ -0,0 +1,69 @@
+package com.thealgorithms.geometry;
+
+import java.awt.Point;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * The {@code BresenhamLine} class implements the Bresenham's line algorithm,
+ * which is an efficient way to determine the points of a straight line
+ * between two given points in a 2D space.
+ *
+ * <p>This algorithm uses integer arithmetic to calculate the points,
+ * making it suitable for rasterization in computer graphics.</p>
+ *
+ * For more information, please visit {@link https://en.wikipedia.org/wiki/Bresenham%27s_line_algorithm}
+ */
+public final class BresenhamLine {
+
+    private BresenhamLine() {
+        // Private constructor to prevent instantiation.
+    }
+
+    /**
+     * Finds the list of points that form a straight line between two endpoints.
+     *
+     * @param x0 the x-coordinate of the starting point
+     * @param y0 the y-coordinate of the starting point
+     * @param x1 the x-coordinate of the ending point
+     * @param y1 the y-coordinate of the ending point
+     * @return a {@code List<Point>} containing all points on the line
+     */
+    public static List<Point> findLine(int x0, int y0, int x1, int y1) {
+        List<Point> line = new ArrayList<>();
+
+        // Calculate differences and steps for each axis
+        int dx = Math.abs(x1 - x0); // Change in x
+        int dy = Math.abs(y1 - y0); // Change in y
+        int sx = (x0 < x1) ? 1 : -1; // Step in x direction
+        int sy = (y0 < y1) ? 1 : -1; // Step in y direction
+        int err = dx - dy; // Initial error term
+
+        // Loop until we reach the endpoint
+        while (true) {
+            line.add(new Point(x0, y0)); // Add current point to the line
+
+            // Check if we've reached the endpoint
+            if (x0 == x1 && y0 == y1) {
+                break; // Exit loop if endpoint is reached
+            }
+
+            // Calculate error term doubled for decision making
+            final int e2 = err * 2;
+
+            // Adjust x coordinate if necessary
+            if (e2 > -dy) {
+                err -= dy; // Update error term
+                x0 += sx; // Move to next point in x direction
+            }
+
+            // Adjust y coordinate if necessary
+            if (e2 < dx) {
+                err += dx; // Update error term
+                y0 += sy; // Move to next point in y direction
+            }
+        }
+
+        return line; // Return the list of points forming the line
+    }
+}

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

@@ -0,0 +1,52 @@
+package com.thealgorithms.stacks;
+
+import java.util.Stack;
+
+/**
+ * Solves the celebrity problem using a stack-based algorithm.
+ *
+ * <p>Celebrity is someone known by everyone but doesn't know anyone else.
+ * <p>Applications: Graph theory and social network analysis.
+ *
+ * @author Hardvan
+ */
+public final class CelebrityFinder {
+    private CelebrityFinder() {
+    }
+
+    /**
+     * Finds the celebrity in the given party matrix using a stack-based algorithm.
+     *
+     * @param party A 2D matrix where party[i][j] is 1 if i knows j, otherwise 0.
+     * @return The index of the celebrity, or -1 if there is no celebrity.
+     */
+    public static int findCelebrity(int[][] party) {
+
+        // Push all people onto the stack
+        Stack<Integer> stack = new Stack<>();
+        for (int i = 0; i < party.length; i++) {
+            stack.push(i);
+        }
+
+        // Find the potential celebrity by comparing pairs
+        while (stack.size() > 1) {
+            int person1 = stack.pop();
+            int person2 = stack.pop();
+
+            if (party[person1][person2] == 1) {
+                stack.push(person2); // person1 knows person2, so person2 might be the celebrity
+            } else {
+                stack.push(person1); // person1 doesn't know person2, so person1 might be the celebrity
+            }
+        }
+
+        // Verify the candidate
+        int candidate = stack.pop();
+        for (int i = 0; i < party.length; i++) {
+            if (i != candidate && (party[candidate][i] == 1 || party[i][candidate] == 0)) {
+                return -1;
+            }
+        }
+        return candidate;
+    }
+}

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

@@ -0,0 +1,57 @@
+package com.thealgorithms.stacks;
+
+import java.util.Stack;
+
+/**
+ * Min-Stack implementation that supports push, pop, and retrieving the minimum element in constant time.
+ *
+ * @author Hardvan
+ */
+public final class MinStackUsingTwoStacks {
+    MinStackUsingTwoStacks() {
+    }
+
+    private final Stack<Integer> stack = new Stack<>();
+    private final Stack<Integer> minStack = new Stack<>();
+
+    /**
+     * Pushes a new element onto the {@code stack}.
+     * If the value is less than or equal to the current minimum, it is also pushed onto the {@code minStack}.
+     *
+     * @param value The value to be pushed.
+     */
+    public void push(int value) {
+        stack.push(value);
+        if (minStack.isEmpty() || value <= minStack.peek()) {
+            minStack.push(value);
+        }
+    }
+
+    /**
+     * Removes the top element from the stack.
+     * If the element is the minimum element, it is also removed from the {@code minStack}.
+     */
+    public void pop() {
+        if (stack.pop().equals(minStack.peek())) {
+            minStack.pop();
+        }
+    }
+
+    /**
+     * Retrieves the top element of the stack.
+     *
+     * @return The top element.
+     */
+    public int top() {
+        return stack.peek();
+    }
+
+    /**
+     * Retrieves the minimum element in the stack.
+     *
+     * @return The minimum element.
+     */
+    public int getMin() {
+        return minStack.peek();
+    }
+}

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

@@ -27,10 +27,14 @@ void testCombinationThrows(int n, int k) {
 
     private static Stream<Arguments> regularInputs() {
         return Stream.of(Arguments.of(0, 0, List.of(new ArrayList<Integer>())), Arguments.of(1, 0, List.of(new ArrayList<Integer>())), Arguments.of(1, 1, List.of(List.of(0))), Arguments.of(3, 0, List.of(new ArrayList<Integer>())), Arguments.of(3, 1, List.of(List.of(0), List.of(1), List.of(2))),
-            Arguments.of(4, 2, List.of(List.of(0, 1), List.of(0, 2), List.of(0, 3), List.of(1, 2), List.of(1, 3), List.of(2, 3))));
+            Arguments.of(4, 2, List.of(List.of(0, 1), List.of(0, 2), List.of(0, 3), List.of(1, 2), List.of(1, 3), List.of(2, 3))),
+            Arguments.of(5, 3, List.of(List.of(0, 1, 2), List.of(0, 1, 3), List.of(0, 1, 4), List.of(0, 2, 3), List.of(0, 2, 4), List.of(0, 3, 4), List.of(1, 2, 3), List.of(1, 2, 4), List.of(1, 3, 4), List.of(2, 3, 4))),
+            Arguments.of(6, 4,
+                List.of(List.of(0, 1, 2, 3), List.of(0, 1, 2, 4), List.of(0, 1, 2, 5), List.of(0, 1, 3, 4), List.of(0, 1, 3, 5), List.of(0, 1, 4, 5), List.of(0, 2, 3, 4), List.of(0, 2, 3, 5), List.of(0, 2, 4, 5), List.of(0, 3, 4, 5), List.of(1, 2, 3, 4), List.of(1, 2, 3, 5), List.of(1, 2, 4, 5),
+                    List.of(1, 3, 4, 5), List.of(2, 3, 4, 5))));
     }
 
     private static Stream<Arguments> wrongInputs() {
-        return Stream.of(Arguments.of(-1, 0), Arguments.of(0, -1), Arguments.of(2, 100));
+        return Stream.of(Arguments.of(-1, 0), Arguments.of(0, -1), Arguments.of(2, 100), Arguments.of(3, 4));
     }
 }

src/test/java/com/thealgorithms/geometry/BresenhamLineTest.java

@@ -0,0 +1,57 @@
+package com.thealgorithms.geometry;
+
+import java.awt.Point;
+import java.util.Collection;
+import java.util.List;
+import java.util.stream.Stream;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+
+/**
+ * The {@code BresenhamLineTest} class contains unit tests for the
+ * {@code BresenhamLine} class, specifically testing the
+ * {@code findLine} method.
+ *
+ * <p>This class uses parameterized tests to validate the output of
+ * Bresenham's line algorithm for various input points.</p>
+ */
+class BresenhamLineTest {
+
+    /**
+     * Provides test cases for the parameterized test.
+     *
+     * <p>Each test case includes starting coordinates, ending coordinates,
+     * and the expected collection of points that should be generated by the
+     * {@code findLine} method.</p>
+     *
+     * @return a stream of arguments containing test cases
+     */
+    static Stream<Arguments> linePointsProvider() {
+        return Stream.of(Arguments.of(0, 0, 5, 5, List.of(new Point(0, 0), new Point(1, 1), new Point(2, 2), new Point(3, 3), new Point(4, 4), new Point(5, 5))), Arguments.of(0, 0, 5, 0, List.of(new Point(0, 0), new Point(1, 0), new Point(2, 0), new Point(3, 0), new Point(4, 0), new Point(5, 0))),
+            Arguments.of(0, 0, 0, 5, List.of(new Point(0, 0), new Point(0, 1), new Point(0, 2), new Point(0, 3), new Point(0, 4), new Point(0, 5))), Arguments.of(-2, -2, -5, -5, List.of(new Point(-2, -2), new Point(-3, -3), new Point(-4, -4), new Point(-5, -5))),
+            Arguments.of(-1, -1, 2, 2, List.of(new Point(-1, -1), new Point(0, 0), new Point(1, 1), new Point(2, 2))), Arguments.of(2, -1, -1, -4, List.of(new Point(2, -1), new Point(1, -2), new Point(0, -3), new Point(-1, -4))));
+    }
+
+    /**
+     * Tests the {@code findLine} method of the {@code BresenhamLine} class.
+     *
+     * <p>This parameterized test runs multiple times with different sets of
+     * starting and ending coordinates to validate that the generated points
+     * match the expected output.</p>
+     *
+     * @param x0      the x-coordinate of the starting point
+     * @param y0      the y-coordinate of the starting point
+     * @param x1      the x-coordinate of the ending point
+     * @param y1      the y-coordinate of the ending point
+     * @param expected a collection of expected points that should form a line
+     */
+    @ParameterizedTest
+    @MethodSource("linePointsProvider")
+    void testFindLine(int x0, int y0, int x1, int y1, Collection<Point> expected) {
+        List<Point> actual = BresenhamLine.findLine(x0, y0, x1, y1);
+        Assertions.assertEquals(expected.size(), actual.size(), "The size of the points list should match.");
+        Assertions.assertTrue(expected.containsAll(actual) && actual.containsAll(expected), "The points generated should match the expected points.");
+    }
+}

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

@@ -0,0 +1,41 @@
+package com.thealgorithms.stacks;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+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;
+
+public class CelebrityFinderTest {
+
+    @ParameterizedTest
+    @MethodSource("providePartyMatrices")
+    public void testCelebrityFinder(int[][] party, int expected) {
+        assertEquals(expected, CelebrityFinder.findCelebrity(party));
+    }
+
+    private static Stream<Arguments> providePartyMatrices() {
+        return Stream.of(
+            // Test case 1: Celebrity exists
+            Arguments.of(new int[][] {{0, 1, 1}, {0, 0, 1}, {0, 0, 0}}, 2),
+
+            // Test case 2: No celebrity
+            Arguments.of(new int[][] {{0, 1, 0}, {1, 0, 1}, {1, 1, 0}}, -1),
+
+            // Test case 3: Everyone knows each other, no celebrity
+            Arguments.of(new int[][] {{0, 1, 1}, {1, 0, 1}, {1, 1, 0}}, -1),
+
+            // Test case 4: Single person, they are trivially a celebrity
+            Arguments.of(new int[][] {{0}}, 0),
+
+            // Test case 5: All know the last person, and they know no one
+            Arguments.of(new int[][] {{0, 1, 1, 1}, {0, 0, 1, 1}, {0, 0, 0, 1}, {0, 0, 0, 0}}, 3),
+
+            // Test case 6: Larger party with no celebrity
+            Arguments.of(new int[][] {{0, 1, 1, 0}, {1, 0, 0, 1}, {0, 1, 0, 1}, {1, 1, 1, 0}}, -1),
+
+            // Test case 7: Celebrity at the start of the matrix
+            Arguments.of(new int[][] {{0, 0, 0}, {1, 0, 1}, {1, 1, 0}}, 0));
+    }
+}