Merge branch 'master' into count_sll_improve

Author: siriak

DIRECTORY.md

@@ -831,6 +831,10 @@
               * [CircleLinkedListTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/CircleLinkedListTest.java)
               * [CountSinglyLinkedListRecursionTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/CountSinglyLinkedListRecursionTest.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)
+              * [MergeKSortedLinkedListTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/lists/MergeKSortedLinkedListTest.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/CursorLinkedList.java

@@ -3,18 +3,20 @@
 import java.util.Objects;
 
 /**
- * This class implements a Cursor Linked List.
- *
- * A CursorLinkedList is an array version of a Linked List. Essentially you have
- * an array of list nodes but instead of each node containing a pointer to the
- * next item in the linked list, each node element in the array contains the
- * index for the next node element.
+ * CursorLinkedList is an array-based implementation of a singly linked list.
+ * Each node in the array simulates a linked list node, storing an element and
+ * the index of the next node. This structure allows for efficient list operations
+ * without relying on traditional pointers.
  *
+ * @param <T> the type of elements in this list
  */
 public class CursorLinkedList<T> {
 
+    /**
+     * Node represents an individual element in the list, containing the element
+     * itself and a pointer (index) to the next node.
+     */
     private static class Node<T> {
-
         T element;
         int next;
 
@@ -31,20 +33,26 @@ private static class Node<T> {
     private static final int CURSOR_SPACE_SIZE = 100;
 
     {
-        // init at loading time
+        // Initialize cursor space array and free list pointers
         cursorSpace = new Node[CURSOR_SPACE_SIZE];
         for (int i = 0; i < CURSOR_SPACE_SIZE; i++) {
             cursorSpace[i] = new Node<>(null, i + 1);
         }
         cursorSpace[CURSOR_SPACE_SIZE - 1].next = 0;
     }
 
+    /**
+     * Constructs an empty CursorLinkedList with the default capacity.
+     */
     public CursorLinkedList() {
         os = 0;
         count = 0;
         head = -1;
     }
 
+    /**
+     * Prints all elements in the list in their current order.
+     */
     public void printList() {
         if (head != -1) {
             int start = head;
@@ -57,27 +65,36 @@ public void printList() {
     }
 
     /**
-     * @return the logical index of the element within the list , not the actual
-     * index of the [cursorSpace] array
+     * Finds the logical index of a specified element in the list.
+     *
+     * @param element the element to search for in the list
+     * @return the logical index of the element, or -1 if not found
+     * @throws NullPointerException if element is null
      */
     public int indexOf(T element) {
-        Objects.requireNonNull(element);
-        Node<T> iterator = cursorSpace[head];
-        for (int i = 0; i < count; i++) {
-            if (iterator.element.equals(element)) {
-                return i;
+        if (element == null) {
+            throw new NullPointerException("Element cannot be null");
+        }
+        try {
+            Objects.requireNonNull(element);
+            Node<T> iterator = cursorSpace[head];
+            for (int i = 0; i < count; i++) {
+                if (iterator.element.equals(element)) {
+                    return i;
+                }
+                iterator = cursorSpace[iterator.next];
             }
-            iterator = cursorSpace[iterator.next];
+        } catch (Exception e) {
+            return -1;
         }
-
         return -1;
     }
 
     /**
-     * @param position , the logical index of the element , not the actual one
-     * within the [cursorSpace] array . this method should be used to get the
-     * index give by indexOf() method.
-     * @return
+     * Retrieves an element at a specified logical index in the list.
+     *
+     * @param position the logical index of the element
+     * @return the element at the specified position, or null if index is out of bounds
      */
     public T get(int position) {
         if (position >= 0 && position < count) {
@@ -88,51 +105,76 @@ public T get(int position) {
                 if (counter == position) {
                     return element;
                 }
-
                 start = cursorSpace[start].next;
                 counter++;
             }
         }
-
         return null;
     }
 
+    /**
+     * Removes the element at a specified logical index from the list.
+     *
+     * @param index the logical index of the element to remove
+     */
     public void removeByIndex(int index) {
         if (index >= 0 && index < count) {
             T element = get(index);
             remove(element);
         }
     }
 
+    /**
+     * Removes a specified element from the list.
+     *
+     * @param element the element to be removed
+     * @throws NullPointerException if element is null
+     */
     public void remove(T element) {
         Objects.requireNonNull(element);
-
-        // case element is in the head
         T tempElement = cursorSpace[head].element;
         int tempNext = cursorSpace[head].next;
         if (tempElement.equals(element)) {
             free(head);
             head = tempNext;
-        } else { // otherwise cases
+        } else {
             int prevIndex = head;
             int currentIndex = cursorSpace[prevIndex].next;
-
             while (currentIndex != -1) {
                 T currentElement = cursorSpace[currentIndex].element;
                 if (currentElement.equals(element)) {
                     cursorSpace[prevIndex].next = cursorSpace[currentIndex].next;
                     free(currentIndex);
                     break;
                 }
-
                 prevIndex = currentIndex;
                 currentIndex = cursorSpace[prevIndex].next;
             }
         }
-
         count--;
     }
 
+    /**
+     * Allocates a new node index for storing an element.
+     *
+     * @return the index of the newly allocated node
+     * @throws OutOfMemoryError if no space is available in cursor space
+     */
+    private int alloc() {
+        int availableNodeIndex = cursorSpace[os].next;
+        if (availableNodeIndex == 0) {
+            throw new OutOfMemoryError();
+        }
+        cursorSpace[os].next = cursorSpace[availableNodeIndex].next;
+        cursorSpace[availableNodeIndex].next = -1;
+        return availableNodeIndex;
+    }
+
+    /**
+     * Releases a node back to the free list.
+     *
+     * @param index the index of the node to release
+     */
     private void free(int index) {
         Node<T> osNode = cursorSpace[os];
         int osNext = osNode.next;
@@ -141,44 +183,26 @@ private void free(int index) {
         cursorSpace[index].next = osNext;
     }
 
+    /**
+     * Appends an element to the end of the list.
+     *
+     * @param element the element to append
+     * @throws NullPointerException if element is null
+     */
     public void append(T element) {
         Objects.requireNonNull(element);
         int availableIndex = alloc();
         cursorSpace[availableIndex].element = element;
-
         if (head == -1) {
             head = availableIndex;
+        } else {
+            int iterator = head;
+            while (cursorSpace[iterator].next != -1) {
+                iterator = cursorSpace[iterator].next;
+            }
+            cursorSpace[iterator].next = availableIndex;
         }
-
-        int iterator = head;
-        while (cursorSpace[iterator].next != -1) {
-            iterator = cursorSpace[iterator].next;
-        }
-
-        cursorSpace[iterator].next = availableIndex;
         cursorSpace[availableIndex].next = -1;
-
         count++;
     }
-
-    /**
-     * @return the index of the next available node
-     */
-    private int alloc() {
-        // 1- get the index at which the os is pointing
-        int availableNodeIndex = cursorSpace[os].next;
-
-        if (availableNodeIndex == 0) {
-            throw new OutOfMemoryError();
-        }
-
-        // 2- make the os point to the next of the  @var{availableNodeIndex}
-        cursorSpace[os].next = cursorSpace[availableNodeIndex].next;
-
-        // this to indicate an end of the list , helpful at testing since any err
-        // would throw an outOfBoundException
-        cursorSpace[availableNodeIndex].next = -1;
-
-        return availableNodeIndex;
-    }
 }