Frequency map approach for finding lucky number

Author: kshitizsaini113

src/main/java/array/lucky_integer/FrequencyMap.java

@@ -0,0 +1,67 @@
+package array.lucky_integer;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Solves the "Find Lucky Integer" problem using a HashMap to count frequencies.
+ *
+ * <p>This approach first iterates through the array to build a frequency map of all
+ * numbers, then iterates through the map to find the largest number whose value
+ * matches its frequency.
+ */
+public class FrequencyMap {
+
+    /**
+     * Finds the largest lucky integer in an array.
+     *
+     * <p>A lucky integer is an integer that has a frequency in the array equal to its value.
+     * This method uses a two-pass approach:
+     * <ol>
+     *   <li>Build a frequency map of all numbers in the input array.</li>
+     *   <li>Iterate through the map to find the largest key that equals its value.</li>
+     * </ol>
+     *
+     * <p><b>Complexity:</b>
+     * <ul>
+     *   <li>Time: O(N), where N is the number of elements in {@code arr}. The first loop
+     *       takes O(N), and the second loop takes O(U), where U is the number of unique
+     *       elements (U &le; N).
+     *   <li>Space: O(U), to store the unique elements in the frequency map.
+     * </ul>
+     *
+     * @param arr The input array of integers. Constraints: 1 &le; arr.length &le; 500,
+     *            1 &le; arr[i] &le; 500.
+     * @return The largest lucky integer in the array, or -1 if none exists.
+     */
+    public int findLucky(int[] arr) {
+        // Step 1: Create a frequency map to count occurrences of each number.
+        // The key is the number from the array, and the value is its frequency.
+        Map<Integer, Integer> freqMap = new HashMap<>();
+        for (int num : arr) {
+            // For each number, increment its count in the map.
+            // getOrDefault handles the case where the number is seen for the first time.
+            freqMap.put(num, freqMap.getOrDefault(num, 0) + 1);
+        }
+
+        // Step 2: Find the largest lucky integer.
+        // Initialize the result to -1, which will be returned if no lucky integer is found.
+        int lucky = -1;
+
+        // Iterate through each entry (number and its count) in the frequency map.
+        for (var entry : freqMap.entrySet()) {
+            int num = entry.getKey();
+            int count = entry.getValue();
+
+            // A number is "lucky" if its value is equal to its frequency.
+            // We also check if this lucky number is greater than the one we've already found.
+            if (num == count && num > lucky) {
+                // If it is, update our result to this new, larger lucky number.
+                lucky = num;
+            }
+        }
+
+        // Return the largest lucky number found, or -1 if none existed.
+        return lucky;
+    }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Provides solutions for the "Find Lucky Integer in an Array" problem.
+ *
+ * <p>The problem is defined as follows: Given an array of integers {@code arr},
+ * a "lucky integer" is an integer whose frequency in the array is equal to its value.
+ *
+ * <p>The goal of the implementations in this package is to find and return the
+ * largest lucky integer from the input array. If no such integer exists, the
+ * implementations will return -1.
+ *
+ * <p>For example, in the array {@code [2, 2, 3, 4]}, the number 2 is a lucky
+ * integer because it appears 2 times. In {@code [1, 2, 2, 3, 3, 3]}, both 1 and 3
+ * are lucky integers, and the correct return value would be 3, as it is the largest.
+ *
+ * <h3>Constraints:</h3>
+ * <ul>
+ *   <li>{@code 1 <= arr.length <= 500}</li>
+ *   <li>{@code 1 <= arr[i] <= 500}</li>
+ * </ul>
+ *
+ * @version 1.0
+ * @see <a href="https://leetcode.com/problems/find-lucky-integer-in-an-array/">LeetCode 1394: Find Lucky Integer in an Array</a>
+ * @since 1.0
+ */
+package array.lucky_integer;

src/test/java/array/lucky_integer/FrequencyMapTest.java

@@ -0,0 +1,105 @@
+package array.lucky_integer;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+/**
+ * Test suite for the {@link FrequencyMap} class.
+ */
+class FrequencyMapTest {
+
+    private FrequencyMap frequencyMap;
+
+    @BeforeEach
+    void setUp() {
+        frequencyMap = new FrequencyMap();
+    }
+
+    @Test
+    @DisplayName("Should return the largest lucky integer when multiple exist")
+    void findLucky_whenMultipleLuckyIntegersExist_shouldReturnLargest() {
+        int[] arr = {1, 2, 2, 3, 3, 3};
+        assertEquals(3, frequencyMap.findLucky(arr), "The largest lucky integer is 3, as 1 and 3 are both lucky.");
+    }
+
+    @Test
+    @DisplayName("Should return a single lucky integer when one exists")
+    void findLucky_whenOneLuckyIntegerExists_shouldReturnIt() {
+        int[] arr = {2, 2, 3, 4};
+        assertEquals(2, frequencyMap.findLucky(arr), "The only lucky integer is 2.");
+    }
+
+    @Test
+    @DisplayName("Should return -1 when no lucky integer exists")
+    void findLucky_whenNoLuckyIntegerExists_shouldReturnMinusOne() {
+        int[] arr = {1, 2, 2, 3, 3, 2, 1};
+        assertEquals(-1, frequencyMap.findLucky(arr), "No number has a frequency equal to its value.");
+    }
+
+    @Test
+    @DisplayName("Should return -1 for an empty array")
+    void findLucky_whenArrayIsEmpty_shouldReturnMinusOne() {
+        int[] arr = {};
+        assertEquals(-1, frequencyMap.findLucky(arr), "An empty array has no lucky integers.");
+    }
+
+    @Test
+    @DisplayName("Should handle an array where all elements are the same and form a lucky number")
+    void findLucky_whenAllElementsAreSameAndLucky_shouldReturnTheNumber() {
+        int[] arr = {4, 4, 4, 4};
+        assertEquals(4, frequencyMap.findLucky(arr), "4 appears 4 times, so it is lucky.");
+    }
+
+    @Test
+    @DisplayName("Should handle an array where all elements are the same but not lucky")
+    void findLucky_whenAllElementsAreSameAndNotLucky_shouldReturnMinusOne() {
+        int[] arr = {5, 5, 5};
+        assertEquals(-1, frequencyMap.findLucky(arr), "5 appears 3 times, so it is not lucky.");
+    }
+
+    @Test
+    @DisplayName("Should handle a single element array that is lucky")
+    void findLucky_whenSingleElementIsLucky_shouldReturnTheNumber() {
+        int[] arr = {1};
+        assertEquals(1, frequencyMap.findLucky(arr), "1 appears 1 time, so it is lucky.");
+    }
+
+    @Test
+    @DisplayName("Should handle a single element array that is not lucky")
+    void findLucky_whenSingleElementIsNotLucky_shouldReturnMinusOne() {
+        int[] arr = {2};
+        assertEquals(-1, frequencyMap.findLucky(arr), "2 appears 1 time, so it is not lucky.");
+    }
+
+    @Test
+    @DisplayName("Should handle a complex case with various numbers")
+    void findLucky_withComplexArray_shouldReturnCorrectLargestLucky() {
+        int[] arr = {7, 7, 7, 7, 7, 7, 7, 5, 5, 5, 5, 5, 2, 2, 8, 9};
+        assertEquals(7, frequencyMap.findLucky(arr), "Both 5 and 7 are lucky, but 7 is the largest.");
+    }
+
+    @Test
+    @DisplayName("Should ignore a smaller lucky number after a larger one is found")
+    void findLucky_shouldNotBeReplacedBySmallerLuckyNumber() {
+        // This test explicitly verifies the `num > lucky` part of the condition.
+        // The map will contain two lucky numbers: 4 (appears 4 times) and 2 (appears 2 times).
+        // The logic must correctly identify 4 as the largest lucky number,
+        // even if it processes 2 after 4.
+        int[] arr = {4, 4, 4, 4, 2, 2};
+        assertEquals(4, frequencyMap.findLucky(arr), "The result should be the largest lucky number (4), not the smaller one (2).");
+    }
+
+    @Test
+    @DisplayName("Should correctly identify the largest lucky number when a smaller one is also present")
+    void findLucky_shouldHandleMultipleLuckyNumbers() {
+        // This test ensures that if a smaller lucky number (e.g., 2) is processed
+        // after a larger one (e.g., 3), the larger one is correctly retained.
+        // This specifically covers the case where `num == count` is true,
+        // but `num > lucky` is false.
+        int[] arr = {2, 2, 3, 3, 3};
+        assertEquals(3, frequencyMap.findLucky(arr), "The largest lucky number should be 3, not 2.");
+    }
+}