refactor: Enhance docs, remove main, add tests in `MergeSortedArray…

DIRECTORY.md

@@ -830,6 +830,7 @@
             * lists
               * [CircleLinkedListTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/CircleLinkedListTest.java)
               * [CreateAndDetectLoopTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/CreateAndDetectLoopTest.java)
+              * [MergeSortedArrayListTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/MergeSortedArrayListTest.java)
               * [QuickSortLinkedListTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/QuickSortLinkedListTest.java)
               * [ReverseKGroupTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/ReverseKGroupTest.java)
               * [RotateSinglyLinkedListsTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/RotateSinglyLinkedListsTest.java)

src/main/java/com/thealgorithms/datastructures/lists/MergeSortedArrayList.java

@@ -1,49 +1,55 @@
 package com.thealgorithms.datastructures.lists;
 
-import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
 
 /**
+ * Utility class for merging two sorted ArrayLists of integers into a single sorted collection.
+ *
+ * <p>This class provides a static `merge` method to combine two pre-sorted lists of integers into a
+ * single sorted list. It does so without modifying the input lists by adding elements from both lists in sorted order
+ * into the result list.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>
+ * List<Integer> listA = Arrays.asList(1, 3, 5, 7, 9);
+ * List<Integer> listB = Arrays.asList(2, 4, 6, 8, 10);
+ * List<Integer> result = new ArrayList<>();
+ * MergeSortedArrayList.merge(listA, listB, result);
+ * </pre>
+ *
+ * <p>The resulting `result` list will be [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].</p>
+ *
+ * <p>Note: This class cannot be instantiated as it is designed to be used only with its static `merge` method.</p>
+ *
+ * <p>This implementation assumes the input lists are already sorted in ascending order.</p>
+ *
  * @author https://github.com/shellhub
+ * @see List
  */
 public final class MergeSortedArrayList {
-    private MergeSortedArrayList() {
-    }
-
-    public static void main(String[] args) {
-        List<Integer> listA = new ArrayList<>();
-        List<Integer> listB = new ArrayList<>();
-        List<Integer> listC = new ArrayList<>();
-
-        /* init ListA and List B */
-        for (int i = 1; i <= 10; i += 2) {
-            listA.add(i);
-            /* listA: [1, 3, 5, 7, 9]  */
-            listB.add(i + 1);
-            /* listB: [2, 4, 6, 8, 10] */
-        }
-
-        /* merge listA and listB to listC */
-        merge(listA, listB, listC);
 
-        System.out.println("listA: " + listA);
-        System.out.println("listB: " + listB);
-        System.out.println("listC: " + listC);
+    private MergeSortedArrayList() {
     }
 
     /**
-     * merge two sorted ArrayList
+     * Merges two sorted lists of integers into a single sorted collection.
+     *
+     * <p>This method does not alter the original lists (`listA` and `listB`). Instead, it inserts elements from both
+     * lists into `listC` in a way that maintains ascending order.</p>
      *
-     * @param listA the first list to merge
-     * @param listB the second list to merge
-     * @param listC the result list after merging
+     * @param listA The first sorted list of integers.
+     * @param listB The second sorted list of integers.
+     * @param listC The collection to hold the merged result, maintaining sorted order.
+     * @throws NullPointerException if any of the input lists or result collection is null.
      */
     public static void merge(List<Integer> listA, List<Integer> listB, Collection<Integer> listC) {
+        if (listA == null || listB == null || listC == null) {
+            throw new NullPointerException("Input lists and result collection must not be null.");
+        }
+
         int pa = 0;
-        /* the index of listA */
         int pb = 0;
-        /* the index of listB */
 
         while (pa < listA.size() && pb < listB.size()) {
             if (listA.get(pa) <= listB.get(pb)) {
@@ -53,12 +59,11 @@ public static void merge(List<Integer> listA, List<Integer> listB, Collection<In
             }
         }
 
-        /* copy left element of listA to listC */
+        // Add remaining elements from listA, if any
         while (pa < listA.size()) {
             listC.add(listA.get(pa++));
         }
-
-        /* copy left element of listB to listC */
+        // Add remaining elements from listB, if any
         while (pb < listB.size()) {
             listC.add(listB.get(pb++));
         }

src/test/java/com/thealgorithms/datastructures/lists/MergeSortedArrayListTest.java

@@ -0,0 +1,99 @@
+package com.thealgorithms.datastructures.lists;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+class MergeSortedArrayListTest {
+
+    @Test
+    void testMergeTwoSortedLists() {
+        List<Integer> listA = Arrays.asList(1, 3, 5, 7, 9);
+        List<Integer> listB = Arrays.asList(2, 4, 6, 8, 10);
+        List<Integer> result = new ArrayList<>();
+
+        MergeSortedArrayList.merge(listA, listB, result);
+
+        List<Integer> expected = Arrays.asList(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
+        assertEquals(expected, result, "Merged list should be sorted and contain all elements from both input lists.");
+    }
+
+    @Test
+    void testMergeWithEmptyList() {
+        List<Integer> listA = Arrays.asList(1, 2, 3);
+        List<Integer> listB = new ArrayList<>(); // Empty list
+        List<Integer> result = new ArrayList<>();
+
+        MergeSortedArrayList.merge(listA, listB, result);
+
+        List<Integer> expected = Arrays.asList(1, 2, 3);
+        assertEquals(expected, result, "Merged list should match listA when listB is empty.");
+    }
+
+    @Test
+    void testMergeWithBothEmptyLists() {
+        List<Integer> listA = new ArrayList<>(); // Empty list
+        List<Integer> listB = new ArrayList<>(); // Empty list
+        List<Integer> result = new ArrayList<>();
+
+        MergeSortedArrayList.merge(listA, listB, result);
+
+        assertTrue(result.isEmpty(), "Merged list should be empty when both input lists are empty.");
+    }
+
+    @Test
+    void testMergeWithDuplicateElements() {
+        List<Integer> listA = Arrays.asList(1, 2, 2, 3);
+        List<Integer> listB = Arrays.asList(2, 3, 4);
+        List<Integer> result = new ArrayList<>();
+
+        MergeSortedArrayList.merge(listA, listB, result);
+
+        List<Integer> expected = Arrays.asList(1, 2, 2, 2, 3, 3, 4);
+        assertEquals(expected, result, "Merged list should correctly handle and include duplicate elements.");
+    }
+
+    @Test
+    void testMergeWithNegativeAndPositiveNumbers() {
+        List<Integer> listA = Arrays.asList(-3, -1, 2);
+        List<Integer> listB = Arrays.asList(-2, 0, 3);
+        List<Integer> result = new ArrayList<>();
+
+        MergeSortedArrayList.merge(listA, listB, result);
+
+        List<Integer> expected = Arrays.asList(-3, -2, -1, 0, 2, 3);
+        assertEquals(expected, result, "Merged list should correctly handle negative and positive numbers.");
+    }
+
+    @Test
+    void testMergeThrowsExceptionOnNullInput() {
+        List<Integer> listA = null;
+        List<Integer> listB = Arrays.asList(1, 2, 3);
+        List<Integer> result = new ArrayList<>();
+
+        List<Integer> finalListB = listB;
+        List<Integer> finalListA = listA;
+        List<Integer> finalResult = result;
+        assertThrows(NullPointerException.class, () -> MergeSortedArrayList.merge(finalListA, finalListB, finalResult), "Should throw NullPointerException if any input list is null.");
+
+        listA = Arrays.asList(1, 2, 3);
+        listB = null;
+        List<Integer> finalListA1 = listA;
+        List<Integer> finalListB1 = listB;
+        List<Integer> finalResult1 = result;
+        assertThrows(NullPointerException.class, () -> MergeSortedArrayList.merge(finalListA1, finalListB1, finalResult1), "Should throw NullPointerException if any input list is null.");
+
+        listA = Arrays.asList(1, 2, 3);
+        listB = Arrays.asList(4, 5, 6);
+        result = null;
+        List<Integer> finalListA2 = listA;
+        List<Integer> finalListB2 = listB;
+        List<Integer> finalResult2 = result;
+        assertThrows(NullPointerException.class, () -> MergeSortedArrayList.merge(finalListA2, finalListB2, finalResult2), "Should throw NullPointerException if the result collection is null.");
+    }
+}