Merge branch 'master' into master

Author: DenizAltunkapan

src/main/java/com/thealgorithms/conversions/AnyBaseToAnyBase.java

@@ -1,3 +1,10 @@
+/**
+ * [Brief description of what the algorithm does]
+ * <p>
+ * Time Complexity: O(n) [or appropriate complexity]
+ * Space Complexity: O(n)
+ * * @author Reshma Kakkirala
+ */
 package com.thealgorithms.conversions;
 
 import java.util.Arrays;

src/main/java/com/thealgorithms/sorts/InsertionSort.java

@@ -33,30 +33,30 @@ public <T extends Comparable<T>> T[] sort(T[] array) {
     }
 
     /**
-     * Sorts a subarray of the given array using the standard Insertion Sort algorithm.
+     * Sorts a subarray of the given items using the standard Insertion Sort algorithm.
      *
-     * @param array The array to be sorted
-     * @param lo    The starting index of the subarray
-     * @param hi    The ending index of the subarray (exclusive)
-     * @param <T>   The type of elements in the array, which must be comparable
-     * @return The sorted array
+     * @param items The items to be sorted
+     * @param startIndex    The starting index of the subarray
+     * @param endIndex    The ending index of the subarray (exclusive)
+     * @param <T>   The type of elements in the items, which must be comparable
+     * @return The sorted items
      */
-    public <T extends Comparable<T>> T[] sort(T[] array, final int lo, final int hi) {
-        if (array == null || lo >= hi) {
-            return array;
+    public <T extends Comparable<T>> T[] sort(T[] items, final int startIndex, final int endIndex) {
+        if (items == null || startIndex >= endIndex) {
+            return items;
         }
 
-        for (int i = lo + 1; i < hi; i++) {
-            final T key = array[i];
+        for (int i = startIndex + 1; i < endIndex; i++) {
+            final T key = items[i];
             int j = i - 1;
-            while (j >= lo && SortUtils.less(key, array[j])) {
-                array[j + 1] = array[j];
+            while (j >= startIndex && SortUtils.less(key, items[j])) {
+                items[j + 1] = items[j];
                 j--;
             }
-            array[j + 1] = key;
+            items[j + 1] = key;
         }
 
-        return array;
+        return items;
     }
 
     /**

src/main/java/com/thealgorithms/sorts/MergeSort.java

@@ -10,7 +10,7 @@
 @SuppressWarnings("rawtypes")
 class MergeSort implements SortAlgorithm {
 
-    private Comparable[] aux;
+    private Comparable[] tempArray;
 
     /**
      * Generic merge sort algorithm.
@@ -26,7 +26,7 @@ class MergeSort implements SortAlgorithm {
      */
     @Override
     public <T extends Comparable<T>> T[] sort(T[] unsorted) {
-        aux = new Comparable[unsorted.length];
+        tempArray = new Comparable[unsorted.length];
         doSort(unsorted, 0, unsorted.length - 1);
         return unsorted;
     }
@@ -58,17 +58,17 @@ private <T extends Comparable<T>> void doSort(T[] arr, int left, int right) {
     private <T extends Comparable<T>> void merge(T[] arr, int left, int mid, int right) {
         int i = left;
         int j = mid + 1;
-        System.arraycopy(arr, left, aux, left, right + 1 - left);
+        System.arraycopy(arr, left, tempArray, left, right + 1 - left);
 
         for (int k = left; k <= right; k++) {
             if (j > right) {
-                arr[k] = (T) aux[i++];
+                arr[k] = (T) tempArray[i++];
             } else if (i > mid) {
-                arr[k] = (T) aux[j++];
-            } else if (less(aux[j], aux[i])) {
-                arr[k] = (T) aux[j++];
+                arr[k] = (T) tempArray[j++];
+            } else if (less(tempArray[j], tempArray[i])) {
+                arr[k] = (T) tempArray[j++];
             } else {
-                arr[k] = (T) aux[i++];
+                arr[k] = (T) tempArray[i++];
             }
         }
     }

src/main/java/com/thealgorithms/sorts/PancakeSort.java

@@ -15,7 +15,7 @@ public <T extends Comparable<T>> T[] sort(T[] array) {
         }
 
         for (int currentSize = 0; currentSize < array.length; currentSize++) {
-            int maxIndex = findMaxIndex(array, currentSize);
+            int maxIndex = findIndexOfMax(array, currentSize);
             SortUtils.flip(array, maxIndex, array.length - 1 - currentSize);
         }
 
@@ -30,7 +30,7 @@ public <T extends Comparable<T>> T[] sort(T[] array) {
      * @param <T>        the type of elements in the array
      * @return the index of the maximum element
      */
-    private <T extends Comparable<T>> int findMaxIndex(T[] array, int currentSize) {
+    private <T extends Comparable<T>> int findIndexOfMax(T[] array, int currentSize) {
         T max = array[0];
         int maxIndex = 0;
         for (int i = 0; i < array.length - currentSize; i++) {

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

@@ -0,0 +1,56 @@
+package com.thealgorithms.strings;
+
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Utility class to find the top-k most frequent words.
+ *
+ * <p>Words are ranked by frequency in descending order. For equal frequencies,
+ * words are ranked in lexicographical ascending order.
+ *
+ * <p>Reference:
+ * https://en.wikipedia.org/wiki/Top-k_problem
+ *
+ */
+public final class TopKFrequentWords {
+    private TopKFrequentWords() {
+    }
+
+    /**
+     * Finds the k most frequent words.
+     *
+     * @param words input array of words
+     * @param k number of words to return
+     * @return list of top-k words ordered by frequency then lexicographical order
+     * @throws IllegalArgumentException if words is null, k is negative, or words contains null
+     */
+    public static List<String> findTopKFrequentWords(String[] words, int k) {
+        if (words == null) {
+            throw new IllegalArgumentException("Input words array cannot be null.");
+        }
+        if (k < 0) {
+            throw new IllegalArgumentException("k cannot be negative.");
+        }
+        if (k == 0 || words.length == 0) {
+            return List.of();
+        }
+
+        Map<String, Integer> frequency = new HashMap<>();
+        for (String word : words) {
+            if (word == null) {
+                throw new IllegalArgumentException("Input words cannot contain null values.");
+            }
+            frequency.put(word, frequency.getOrDefault(word, 0) + 1);
+        }
+
+        List<String> candidates = new ArrayList<>(frequency.keySet());
+        candidates.sort(Comparator.<String>comparingInt(frequency::get).reversed().thenComparing(Comparator.naturalOrder()));
+
+        int limit = Math.min(k, candidates.size());
+        return new ArrayList<>(candidates.subList(0, limit));
+    }
+}

src/test/java/com/thealgorithms/strings/TopKFrequentWordsTest.java

@@ -0,0 +1,34 @@
+package com.thealgorithms.strings;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.util.List;
+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 TopKFrequentWordsTest {
+
+    @ParameterizedTest
+    @MethodSource("validTestCases")
+    void testFindTopKFrequentWords(String[] words, int k, List<String> expected) {
+        assertEquals(expected, TopKFrequentWords.findTopKFrequentWords(words, k));
+    }
+
+    static Stream<Arguments> validTestCases() {
+        return Stream.of(Arguments.of(new String[] {"i", "love", "leetcode", "i", "love", "coding"}, 2, List.of("i", "love")), Arguments.of(new String[] {"the", "day", "is", "sunny", "the", "the", "the", "sunny", "is", "is"}, 4, List.of("the", "is", "sunny", "day")),
+            Arguments.of(new String[] {"bbb", "aaa", "bbb", "aaa", "ccc"}, 2, List.of("aaa", "bbb")), Arguments.of(new String[] {"one", "two", "three"}, 10, List.of("one", "three", "two")), Arguments.of(new String[] {}, 3, List.of()), Arguments.of(new String[] {"x", "x", "y"}, 0, List.of()));
+    }
+
+    @ParameterizedTest
+    @MethodSource("invalidTestCases")
+    void testFindTopKFrequentWordsInvalidInput(String[] words, int k) {
+        assertThrows(IllegalArgumentException.class, () -> TopKFrequentWords.findTopKFrequentWords(words, k));
+    }
+
+    static Stream<Arguments> invalidTestCases() {
+        return Stream.of(Arguments.of((String[]) null, 1), Arguments.of(new String[] {"a", null, "b"}, 2), Arguments.of(new String[] {"a"}, -1));
+    }
+}