Peak Element - Leetcode 162

Author: kshitizsaini113

src/main/java/array/peak_element/BinarySearch.java

@@ -0,0 +1,58 @@
+package array.peak_element;
+
+/**
+ * Implements a solution to find a peak element using binary search.
+ */
+public class BinarySearch {
+
+    /**
+     * Finds a peak element in an array using a modified binary search algorithm.
+     *
+     * <p>The O(log n) time complexity requirement is met by applying binary search.
+     * The algorithm works by comparing the middle element {@code nums[mid]} with
+     * its right neighbor {@code nums[mid + 1]}.
+     * <ul>
+     *   <li>If {@code nums[mid] < nums[mid + 1]}, it implies that the array is
+     *       "climbing" upwards. A peak must exist on the right side, so we
+     *       discard the left half by setting {@code low = mid + 1}.</li>
+     *   <li>If {@code nums[mid] >= nums[mid + 1]}, it implies that {@code nums[mid]}
+     *       is either a peak itself or is on a "downward" slope. In this case,
+     *       a peak is guaranteed to be in the left half (including {@code mid}),
+     *       so we discard the right half by setting {@code high = mid}.</li>
+     * </ul>
+     * The loop continues until {@code low} and {@code high} converge, at which
+     * point they identify the index of a peak element. This approach elegantly
+     * handles all cases, including peaks at the array boundaries, due to the
+     * problem's assumption that elements outside the array are negative infinity.
+     *
+     * @param nums The 0-indexed integer array to search.
+     * @return The index of any peak element.
+     */
+    public int peakElement(int[] nums) {
+        if (nums == null || nums.length == 0) {
+            // Returning -1 or throwing an exception are valid strategies.
+            throw new IllegalArgumentException("Input array cannot be null or empty.");
+        }
+
+        int low = 0;
+        int high = nums.length - 1;
+
+        // Binary search until the search space is reduced to a single element.
+        while (low < high) {
+            // Prevent potential integer overflow
+            int mid = low + (high - low) / 2;
+
+            // If the middle element is less than its right neighbor, a peak
+            // must be in the right half of the array.
+            if (nums[mid] < nums[mid + 1]) {
+                low = mid + 1;
+            } else {
+                // Otherwise, the peak is in the left half, including mid itself.
+                high = mid;
+            }
+        }
+
+        // When the loop terminates, low == high, pointing to a peak element.
+        return low;
+    }
+}

src/main/java/array/peak_element/package-info.java

@@ -0,0 +1,21 @@
+/**
+ * Provides solutions for finding a peak element in an array.
+ *
+ * <h2>Problem: Find Peak Element</h2>
+ *
+ * <p>A peak element is an element that is strictly greater than its neighbors.
+ * Given a 0-indexed integer array {@code nums}, the goal is to find a peak
+ * element and return its index. If the array contains multiple peaks, returning
+ * the index to any of the peaks is acceptable.
+ *
+ * <p>A key condition is that we can imagine {@code nums[-1] = nums[n] = -∞}.
+ * This means an element at the edge of the array only needs to be greater than
+ * its single adjacent neighbor to be considered a peak. This condition also
+ * guarantees that a peak element always exists.
+ *
+ * <p>The solution must run in O(log n) time complexity.
+ *
+ * <p></p>For more details, see the problem on LeetCode:
+ * <a href="https://leetcode.com/problems/find-peak-element/">162. Find Peak Element</a>
+ */
+package array.peak_element;

src/test/java/array/peak_element/BinarySearchTest.java

@@ -0,0 +1,111 @@
+package array.peak_element;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Test suite for the BinarySearch class to find a peak element.
+ */
+class BinarySearchTest {
+
+    private BinarySearch binarySearch;
+
+    @BeforeEach
+    void setUp() {
+        binarySearch = new BinarySearch();
+    }
+
+    @Test
+    @DisplayName("Test with a simple peak in the middle of the array")
+    void testPeakElement_simplePeak() {
+        int[] nums = {1, 2, 3, 1};
+        assertEquals(2, binarySearch.peakElement(nums), "Should find the peak at index 2");
+    }
+
+    @Test
+    @DisplayName("Test with a peak at the beginning of the array")
+    void testPeakElement_peakAtStart() {
+        int[] nums = {5, 4, 3, 2, 1};
+        assertEquals(0, binarySearch.peakElement(nums), "Should find the peak at the start");
+    }
+
+    @Test
+    @DisplayName("Test with a peak at the end of the array")
+    void testPeakElement_peakAtEnd() {
+        int[] nums = {1, 2, 3, 4, 5};
+        assertEquals(4, binarySearch.peakElement(nums), "Should find the peak at the end");
+    }
+
+    @Test
+    @DisplayName("Test with multiple peaks, should return any valid peak index")
+    void testPeakElement_multiplePeaks() {
+        int[] nums = {1, 2, 1, 3, 5, 6, 4};
+        // Valid peaks are at index 1 (value 2) and index 5 (value 6)
+        Set<Integer> validPeakIndices = Set.of(1, 5);
+        int result = binarySearch.peakElement(nums);
+        assertTrue(validPeakIndices.contains(result), "Result should be one of the valid peak indices");
+    }
+
+    @Test
+    @DisplayName("Test with a single-element array")
+    void testPeakElement_singleElement() {
+        int[] nums = {42};
+        assertEquals(0, binarySearch.peakElement(nums), "A single element is always a peak");
+    }
+
+    @Test
+    @DisplayName("Test with a two-element ascending array")
+    void testPeakElement_twoElementsAscending() {
+        int[] nums = {10, 20};
+        assertEquals(1, binarySearch.peakElement(nums), "Peak should be the larger element at index 1");
+    }
+
+    @Test
+    @DisplayName("Test with a two-element descending array")
+    void testPeakElement_twoElementsDescending() {
+        int[] nums = {20, 10};
+        assertEquals(0, binarySearch.peakElement(nums), "Peak should be the larger element at index 0");
+    }
+
+    @Test
+    @DisplayName("Test with an array containing a plateau")
+    void testPeakElement_withPlateau() {
+        int[] nums = {1, 5, 5, 2};
+        // The algorithm should find index 1 as a peak because nums[1] >= nums[2]
+        assertEquals(1, binarySearch.peakElement(nums), "Should handle plateaus correctly");
+    }
+
+    @Test
+    @DisplayName("Test with a zig-zag array")
+    void testPeakElement_zigZag() {
+        int[] nums = {1, 5, 1, 5, 1, 5, 1};
+        Set<Integer> validPeakIndices = Set.of(1, 3, 5);
+        int result = binarySearch.peakElement(nums);
+        assertTrue(validPeakIndices.contains(result), "Result should be a valid peak in the zig-zag array");
+    }
+
+    @Test
+    @DisplayName("Test with a long, strictly increasing then decreasing array")
+    void testPeakElement_longArray() {
+        int[] nums = {1, 2, 3, 4, 5, 6, 7, 8, 7, 6, 5, 4, 3, 2, 1};
+        assertEquals(7, binarySearch.peakElement(nums), "Should find the peak in a long array");
+    }
+
+    @Test
+    @DisplayName("Test with null input should throw IllegalArgumentException")
+    void testPeakElement_nullInput() {
+        assertThrows(IllegalArgumentException.class, () -> binarySearch.peakElement(null), "Should throw IllegalArgumentException for null input");
+    }
+
+    @Test
+    @DisplayName("Test with empty input should throw IllegalArgumentException")
+    void testPeakElement_emptyInput() {
+        int[] nums = {};
+        assertThrows(IllegalArgumentException.class, () -> binarySearch.peakElement(nums), "Should throw IllegalArgumentException for an empty array");
+    }
+}