Merge branch 'master' into cursor_ll_improve

Author: siriak

DIRECTORY.md

@@ -831,6 +831,8 @@
               * [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)
               * [CursorLinkedListTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/CursorLinkedListTest.java)
+              * [MergeSortedArrayListTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/MergeSortedArrayListTest.java)
+              * [MergeSortedSinglyLinkedListTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/MergeSortedSinglyLinkedListTest.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/CreateAndDetectLoop.java

@@ -1,11 +1,24 @@
 package com.thealgorithms.datastructures.lists;
 
+/**
+ * CreateAndDetectLoop provides utility methods for creating and detecting loops
+ * (cycles) in a singly linked list. Loops in a linked list are created by
+ * connecting the "next" pointer of one node to a previous node in the list,
+ * forming a cycle.
+ */
 public final class CreateAndDetectLoop {
 
-    // Node class representing a single node in the linked list
+    /**
+     * Private constructor to prevent instantiation of this utility class.
+     */
     private CreateAndDetectLoop() {
         throw new UnsupportedOperationException("Utility class");
     }
+
+    /**
+     * Node represents an individual element in the linked list, containing
+     * data and a reference to the next node.
+     */
     static final class Node {
         int data;
         Node next;
@@ -16,19 +29,16 @@ static final class Node {
         }
     }
 
-    // Method to create a loop between two specific positions in the linked list
-    /*
-     *  Test case that shows the Cycle(loop) in a LinkedList
-     *  Let's take this linked list:
-     *  1->2->3->4->5->6
-     *     \______/
-     *   In this linked list we can see there is a cycle.
-     *   we can create loop by calling createLoop function in main after creating LL
-     *   createLoop(head,2,5);
-     *  to detect there is loop or not we can call detectloop function in main
-     *  detectloop(head);
+    /**
+     * Creates a loop in a linked list by connecting the next pointer of a node
+     * at a specified starting position (position2) to another node at a specified
+     * destination position (position1). If either position is invalid, no loop
+     * will be created.
+     *
+     * @param head the head node of the linked list
+     * @param position1 the position in the list where the loop should end
+     * @param position2 the position in the list where the loop should start
      */
-
     static void createLoop(Node head, int position1, int position2) {
         if (position1 == 0 || position2 == 0) {
             return;
@@ -39,29 +49,32 @@ static void createLoop(Node head, int position1, int position2) {
 
         int count1 = 1;
         int count2 = 1;
-        // Traverse to find node at position1
+        // Traverse to the node at position1
         while (count1 < position1 && node1 != null) {
             node1 = node1.next;
             count1++;
         }
 
-        // Traverse to find node at position2
+        // Traverse to the node at position2
         while (count2 < position2 && node2 != null) {
             node2 = node2.next;
             count2++;
         }
 
-        // Create a loop by connecting node2's next to node1
+        // If both nodes are valid, create the loop
         if (node1 != null && node2 != null) {
             node2.next = node1;
         }
     }
-    // Method to detect a loop in the linked list
+
     /**
-     * Detects the presence of a loop in the linked list.
+     * Detects the presence of a loop in the linked list using Floyd's cycle-finding
+     * algorithm, also known as the "tortoise and hare" method.
      *
-     * @see <a href="https://en.wikipedia.org/wiki/Cycle_detection#Floyd's_tortoise_and_hare">Floyd's Cycle Detection Algorithm</a>
-     * @return true if loop exists else false
+     * @param head the head node of the linked list
+     * @return true if a loop is detected, false otherwise
+     * @see <a href="https://en.wikipedia.org/wiki/Cycle_detection#Floyd's_tortoise_and_hare">
+     *     Floyd's Cycle Detection Algorithm</a>
      */
     static boolean detectLoop(Node head) {
         Node sptr = head;

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/main/java/com/thealgorithms/datastructures/lists/MergeSortedSinglyLinkedList.java

@@ -1,31 +1,49 @@
 package com.thealgorithms.datastructures.lists;
 
+/**
+ * Utility class for merging two sorted singly linked lists.
+ *
+ * <p>This class extends the {@link SinglyLinkedList} class to support the merging of two sorted linked lists.
+ * It provides a static method, `merge`, that takes two sorted singly linked lists, merges them into a single sorted linked list,
+ * and returns the result.</p>
+ *
+ * <p>Example usage:</p>
+ * <pre>
+ * SinglyLinkedList listA = new SinglyLinkedList();
+ * SinglyLinkedList listB = new SinglyLinkedList();
+ * for (int i = 2; i <= 10; i += 2) {
+ *     listA.insert(i);   // listA: 2->4->6->8->10
+ *     listB.insert(i - 1); // listB: 1->3->5->7->9
+ * }
+ * SinglyLinkedList mergedList = MergeSortedSinglyLinkedList.merge(listA, listB);
+ * System.out.println(mergedList); // Output: 1->2->3->4->5->6->7->8->9->10
+ * </pre>
+ *
+ * <p>The `merge` method assumes that both input lists are already sorted in ascending order.
+ * It returns a new singly linked list that contains all elements from both lists in sorted order.</p>
+ *
+ * @see SinglyLinkedList
+ */
 public class MergeSortedSinglyLinkedList extends SinglyLinkedList {
 
-    public static void main(String[] args) {
-        SinglyLinkedList listA = new SinglyLinkedList();
-        SinglyLinkedList listB = new SinglyLinkedList();
-
-        for (int i = 2; i <= 10; i += 2) {
-            listA.insert(i);
-            listB.insert(i - 1);
-        }
-        assert listA.toString().equals("2->4->6->8->10");
-        assert listB.toString().equals("1->3->5->7->9");
-        assert merge(listA, listB).toString().equals("1->2->3->4->5->6->7->8->9->10");
-    }
-
     /**
-     * Merge two sorted SingleLinkedList
+     * Merges two sorted singly linked lists into a single sorted singly linked list.
+     *
+     * <p>This method does not modify the input lists; instead, it creates a new merged linked list
+     * containing all elements from both lists in sorted order.</p>
      *
-     * @param listA the first sorted list
-     * @param listB the second sored list
-     * @return merged sorted list
+     * @param listA The first sorted singly linked list.
+     * @param listB The second sorted singly linked list.
+     * @return A new singly linked list containing all elements from both lists in sorted order.
+     * @throws NullPointerException if either input list is null.
      */
     public static SinglyLinkedList merge(SinglyLinkedList listA, SinglyLinkedList listB) {
+        if (listA == null || listB == null) {
+            throw new NullPointerException("Input lists must not be null.");
+        }
+
         Node headA = listA.getHead();
         Node headB = listB.getHead();
-
         int size = listA.size() + listB.size();
 
         Node head = new Node();
@@ -40,12 +58,10 @@ public static SinglyLinkedList merge(SinglyLinkedList listA, SinglyLinkedList li
             }
             tail = tail.next;
         }
-        if (headA == null) {
-            tail.next = headB;
-        }
-        if (headB == null) {
-            tail.next = headA;
-        }
+
+        // Attach remaining nodes
+        tail.next = (headA == null) ? headB : headA;
+
         return new SinglyLinkedList(head.next, size);
     }
 }

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

@@ -104,36 +104,52 @@
 
 public class QuickSortLinkedList {
 
-    private SinglyLinkedList list = null; // Linked list
-    private Node head = null; // head of the list
-    // Counstructor
+    private final SinglyLinkedList list; // The linked list to be sorted
+    private Node head; // Head of the list
+
+    /**
+     * Constructor that initializes the QuickSortLinkedList with a given linked list.
+     *
+     * @param list The singly linked list to be sorted
+     */
     public QuickSortLinkedList(SinglyLinkedList list) {
         this.list = list;
         this.head = list.getHead();
     }
 
-    // Function to sort a linked list using the Quick Sort algorithm
+    /**
+     * Sorts the linked list using the QuickSort algorithm.
+     * The sorted list replaces the original list within the SinglyLinkedList instance.
+     */
     public void sortList() {
         head = sortList(head);
         list.setHead(head);
     }
-    // helper function to apply QuickSort to the stored list
-    public Node sortList(Node head) {
+
+    /**
+     * Recursively sorts a linked list by partitioning it around a pivot element.
+     *
+     * <p>Each recursive call selects a pivot, partitions the list into elements less
+     * than the pivot and elements greater than or equal to the pivot, then combines
+     * the sorted sublists around the pivot.</p>
+     *
+     * @param head The head node of the list to sort
+     * @return The head node of the sorted linked list
+     */
+    private Node sortList(Node head) {
         if (head == null || head.next == null) {
             return head;
         }
 
-        // Choose the first element as the pivot
         Node pivot = head;
         head = head.next;
         pivot.next = null;
 
-        Node lessHead = new Node(); // stores the nodes cantaining data less than pivot node
-        Node lessTail = lessHead; // tail of lessHead
-        Node greaterHead = new Node(); // stores the nodes cantaining data greater than pivot node
-        Node greaterTail = greaterHead; // tail of greaterHead
+        Node lessHead = new Node();
+        Node lessTail = lessHead;
+        Node greaterHead = new Node();
+        Node greaterTail = greaterHead;
 
-        // Partition the list around the pivot
         while (head != null) {
             if (head.value < pivot.value) {
                 lessTail.next = head;
@@ -145,15 +161,12 @@ public Node sortList(Node head) {
             head = head.next;
         }
 
-        // Seperating lessHead and greaterHead to form two seperate linkedList
         lessTail.next = null;
         greaterTail.next = null;
 
-        // Recursively sort the sublists
         Node sortedLess = sortList(lessHead.next);
         Node sortedGreater = sortList(greaterHead.next);
 
-        // Combine the sorted sublists and pivot
         if (sortedLess == null) {
             pivot.next = sortedGreater;
             return pivot;