feat: Add Nearest Greater and Smaller Element Algorithms

Author: sgindeed

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

@@ -1,73 +1,101 @@
 package com.thealgorithms.stacks;
 
 import java.util.Stack;
-import java.util.Arrays;
 
+/**
+ * This class provides four algorithms to find the nearest greater or smaller elements
+ * on either side of each element in an array using a stack.
+ *
+ * <p>These algorithms are fundamental examples of the monotonic stack approach, commonly
+ * used in competitive programming and technical interviews. Each method runs in O(n)
+ * time complexity and O(n) space complexity.
+ */
 public final class NearestElement {
 
+    // Private constructor to prevent instantiation
     private NearestElement() {}
 
+    /**
+     * Finds the nearest greater element to the right for each element in the array.
+     *
+     * @param arr the input array
+     * @return an array containing the nearest greater element to the right for each element
+     */
     public static int[] nearestGreaterToRight(int[] arr) {
         int n = arr.length;
         int[] result = new int[n];
-        Stack<Integer> indexStack = new Stack<>();
+        Stack<Integer> stack = new Stack<>();
+
         for (int i = n - 1; i >= 0; i--) {
-            while (!indexStack.isEmpty() && arr[i] >= arr[indexStack.peek()]) {
-                indexStack.pop();
+            while (!stack.isEmpty() && stack.peek() <= arr[i]) {
+                stack.pop();
             }
-            result[i] = indexStack.isEmpty() ? -1 : arr[indexStack.peek()];
-            indexStack.push(i);
+            result[i] = stack.isEmpty() ? -1 : stack.peek();
+            stack.push(arr[i]);
         }
         return result;
     }
 
+    /**
+     * Finds the nearest greater element to the left for each element in the array.
+     *
+     * @param arr the input array
+     * @return an array containing the nearest greater element to the left for each element
+     */
     public static int[] nearestGreaterToLeft(int[] arr) {
         int n = arr.length;
         int[] result = new int[n];
-        Stack<Integer> indexStack = new Stack<>();
+        Stack<Integer> stack = new Stack<>();
+
         for (int i = 0; i < n; i++) {
-            while (!indexStack.isEmpty() && arr[i] >= arr[indexStack.peek()]) {
-                indexStack.pop();
+            while (!stack.isEmpty() && stack.peek() <= arr[i]) {
+                stack.pop();
             }
-            result[i] = indexStack.isEmpty() ? -1 : arr[indexStack.peek()];
-            indexStack.push(i);
+            result[i] = stack.isEmpty() ? -1 : stack.peek();
+            stack.push(arr[i]);
         }
         return result;
     }
 
+    /**
+     * Finds the nearest smaller element to the right for each element in the array.
+     *
+     * @param arr the input array
+     * @return an array containing the nearest smaller element to the right for each element
+     */
     public static int[] nearestSmallerToRight(int[] arr) {
         int n = arr.length;
         int[] result = new int[n];
-        Stack<Integer> indexStack = new Stack<>();
+        Stack<Integer> stack = new Stack<>();
+
         for (int i = n - 1; i >= 0; i--) {
-            while (!indexStack.isEmpty() && arr[i] <= arr[indexStack.peek()]) {
-                indexStack.pop();
+            while (!stack.isEmpty() && stack.peek() >= arr[i]) {
+                stack.pop();
             }
-            result[i] = indexStack.isEmpty() ? -1 : arr[indexStack.peek()];
-            indexStack.push(i);
+            result[i] = stack.isEmpty() ? -1 : stack.peek();
+            stack.push(arr[i]);
         }
         return result;
     }
 
+    /**
+     * Finds the nearest smaller element to the left for each element in the array.
+     *
+     * @param arr the input array
+     * @return an array containing the nearest smaller element to the left for each element
+     */
     public static int[] nearestSmallerToLeft(int[] arr) {
         int n = arr.length;
         int[] result = new int[n];
-        Stack<Integer> indexStack = new Stack<>();
+        Stack<Integer> stack = new Stack<>();
+
         for (int i = 0; i < n; i++) {
-            while (!indexStack.isEmpty() && arr[i] <= arr[indexStack.peek()]) {
-                indexStack.pop();
+            while (!stack.isEmpty() && stack.peek() >= arr[i]) {
+                stack.pop();
             }
-            result[i] = indexStack.isEmpty() ? -1 : arr[indexStack.peek()];
-            indexStack.push(i);
+            result[i] = stack.isEmpty() ? -1 : stack.peek();
+            stack.push(arr[i]);
         }
         return result;
     }
-
-    public static void main(String[] args) {
-        int[] sampleArray = {4, 5, 2, 10, 8};
-        System.out.println("Nearest Greater to Right: " + Arrays.toString(nearestGreaterToRight(sampleArray)));
-        System.out.println("Nearest Greater to Left: " + Arrays.toString(nearestGreaterToLeft(sampleArray)));
-        System.out.println("Nearest Smaller to Right: " + Arrays.toString(nearestSmallerToRight(sampleArray)));
-        System.out.println("Nearest Smaller to Left: " + Arrays.toString(nearestSmallerToLeft(sampleArray)));
-    }
 }

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

@@ -1,56 +1,77 @@
 package com.thealgorithms.stacks;
 
-import org.junit.jupiter.api.Test;
 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.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
 
-public class NearestElementTest {
+class NearestElementTest {
 
-    @Test
-    public void testNearestGreaterToRight() {
-        int[] arr = {4, 5, 2, 10, 8};
-        int[] expected = {5, 10, 10, -1, -1};
-        assertArrayEquals(expected, NearestElement.nearestGreaterToRight(arr));
+    @ParameterizedTest
+    @MethodSource("provideGreaterToRightTestCases")
+    void testNearestGreaterToRight(int[] input, int[] expected) {
+        assertArrayEquals(expected, NearestElement.nearestGreaterToRight(input));
     }
 
-    @Test
-    public void testNearestGreaterToLeft() {
-        int[] arr = {4, 5, 2, 10, 8};
-        int[] expected = {-1, -1, 5, -1, 10};
-        assertArrayEquals(expected, NearestElement.nearestGreaterToLeft(arr));
+    static Stream<Arguments> provideGreaterToRightTestCases() {
+        return Stream.of(
+                Arguments.of(new int[] {4, 5, 2, 10, 8}, new int[] {5, 10, 10, -1, -1}),
+                Arguments.of(new int[] {5}, new int[] {-1}),
+                Arguments.of(new int[] {}, new int[] {})
+        );
     }
 
-    @Test
-    public void testNearestSmallerToRight() {
-        int[] arr = {4, 5, 2, 10, 8};
-        int[] expected = {2, 2, -1, 8, -1};
-        assertArrayEquals(expected, NearestElement.nearestSmallerToRight(arr));
+    @ParameterizedTest
+    @MethodSource("provideGreaterToLeftTestCases")
+    void testNearestGreaterToLeft(int[] input, int[] expected) {
+        assertArrayEquals(expected, NearestElement.nearestGreaterToLeft(input));
     }
 
-    @Test
-    public void testNearestSmallerToLeft() {
-        int[] arr = {4, 5, 2, 10, 8};
-        int[] expected = {-1, 4, -1, 2, 2};
-        assertArrayEquals(expected, NearestElement.nearestSmallerToLeft(arr));
+    static Stream<Arguments> provideGreaterToLeftTestCases() {
+        return Stream.of(
+                Arguments.of(new int[] {4, 5, 2, 10, 8}, new int[] {-1, -1, 5, -1, 10}),
+                Arguments.of(new int[] {5}, new int[] {-1}),
+                Arguments.of(new int[] {}, new int[] {})
+        );
     }
 
-    @Test
-    void testEmptyArray() {
-        int[] arr = {};
-        assertArrayEquals(new int[]{}, NearestElement.nearestGreaterToRight(arr));
-        assertArrayEquals(new int[]{}, NearestElement.nearestGreaterToLeft(arr));
+    @ParameterizedTest
+    @MethodSource("provideSmallerToRightTestCases")
+    void testNearestSmallerToRight(int[] input, int[] expected) {
+        assertArrayEquals(expected, NearestElement.nearestSmallerToRight(input));
     }
 
-    @Test
-    void testAllEqualElements() {
-        int[] arr = {5, 5, 5, 5};
-        assertArrayEquals(new int[]{-1, -1, -1, -1}, NearestElement.nearestGreaterToRight(arr));
-        assertArrayEquals(new int[]{-1, -1, -1, -1}, NearestElement.nearestGreaterToLeft(arr));
+    static Stream<Arguments> provideSmallerToRightTestCases() {
+        return Stream.of(
+                Arguments.of(new int[] {4, 5, 2, 10, 8}, new int[] {2, 2, -1, 8, -1}),
+                Arguments.of(new int[] {5}, new int[] {-1}),
+                Arguments.of(new int[] {}, new int[] {})
+        );
+    }
+
+    @ParameterizedTest
+    @MethodSource("provideSmallerToLeftTestCases")
+    void testNearestSmallerToLeft(int[] input, int[] expected) {
+        assertArrayEquals(expected, NearestElement.nearestSmallerToLeft(input));
+    }
+
+    static Stream<Arguments> provideSmallerToLeftTestCases() {
+        return Stream.of(
+                Arguments.of(new int[] {4, 5, 2, 10, 8}, new int[] {-1, 4, -1, 2, 2}),
+                Arguments.of(new int[] {5}, new int[] {-1}),
+                Arguments.of(new int[] {}, new int[] {})
+        );
     }
 
     @Test
-    void testPrivateConstructor() throws Exception {
-        var constructor = NearestElement.class.getDeclaredConstructor();
-        constructor.setAccessible(true);
-        constructor.newInstance();
+    void testNullInput() {
+        assertThrows(IllegalArgumentException.class, () -> NearestElement.nearestGreaterToRight(null));
+        assertThrows(IllegalArgumentException.class, () -> NearestElement.nearestGreaterToLeft(null));
+        assertThrows(IllegalArgumentException.class, () -> NearestElement.nearestSmallerToRight(null));
+        assertThrows(IllegalArgumentException.class, () -> NearestElement.nearestSmallerToLeft(null));
     }
 }