Merge branch 'origin/sliding-window'

Author: Chiefpatwal

DIRECTORY.md

@@ -829,7 +829,11 @@
               * [LeftistHeapTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/heaps/LeftistHeapTest.java)
             * lists
               * [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)

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

@@ -1,8 +1,23 @@
 package com.thealgorithms.datastructures.lists;
 
+/**
+ * This class is a circular singly linked list implementation. In a circular linked list,
+ * the last node points back to the first node, creating a circular chain.
+ *
+ * <p>This implementation includes basic operations such as appending elements
+ * to the end, removing elements from a specified position, and converting
+ * the list to a string representation.
+ *
+ * @param <E> the type of elements held in this list
+ */
 public class CircleLinkedList<E> {
 
-    private static final class Node<E> {
+    /**
+     * A static nested class representing a node in the circular linked list.
+     *
+     * @param <E> the type of element stored in the node
+     */
+    static final class Node<E> {
 
         Node<E> next;
         E value;
@@ -13,44 +28,56 @@ private Node(E value, Node<E> next) {
         }
     }
 
-    // For better O.O design this should be private allows for better black box design
     private int size;
-    // this will point to dummy node;
-    private Node<E> head = null;
-    private Node<E> tail = null; // keeping a tail pointer to keep track of the end of list
+    Node<E> head = null;
+    private Node<E> tail;
 
-    // constructor for class.. here we will make a dummy node for circly linked list implementation
-    // with reduced error catching as our list will never be empty;
+    /**
+     * Initializes a new circular linked list. A dummy head node is used for simplicity,
+     * pointing initially to itself to ensure the list is never empty.
+     */
     public CircleLinkedList() {
-        // creation of the dummy node
-        head = new Node<E>(null, head);
+        head = new Node<>(null, head);
         tail = head;
         size = 0;
     }
 
-    // getter for the size... needed because size is private.
+    /**
+     * Returns the current size of the list.
+     *
+     * @return the number of elements in the list
+     */
     public int getSize() {
         return size;
     }
 
-    // for the sake of simplistiy this class will only contain the append function or addLast other
-    // add functions can be implemented however this is the basses of them all really.
+    /**
+     * Appends a new element to the end of the list. Throws a NullPointerException if
+     * a null value is provided.
+     *
+     * @param value the value to append to the list
+     * @throws NullPointerException if the value is null
+     */
     public void append(E value) {
         if (value == null) {
-            // we do not want to add null elements to the list.
             throw new NullPointerException("Cannot add null element to the list");
         }
-        // head.next points to the last element;
         if (tail == null) {
-            tail = new Node<E>(value, head);
+            tail = new Node<>(value, head);
             head.next = tail;
         } else {
-            tail.next = new Node<E>(value, head);
+            tail.next = new Node<>(value, head);
             tail = tail.next;
         }
         size++;
     }
 
+    /**
+     * Returns a string representation of the list in the format "[ element1, element2, ... ]".
+     * An empty list is represented as "[]".
+     *
+     * @return the string representation of the list
+     */
     public String toString() {
         if (size == 0) {
             return "[]";
@@ -68,23 +95,27 @@ public String toString() {
         return sb.toString();
     }
 
+    /**
+     * Removes and returns the element at the specified position in the list.
+     * Throws an IndexOutOfBoundsException if the position is invalid.
+     *
+     * @param pos the position of the element to remove
+     * @return the value of the removed element
+     * @throws IndexOutOfBoundsException if the position is out of range
+     */
     public E remove(int pos) {
         if (pos >= size || pos < 0) {
-            // catching errors
-            throw new IndexOutOfBoundsException("position cannot be greater than size or negative");
+            throw new IndexOutOfBoundsException("Position out of bounds");
         }
-        // we need to keep track of the element before the element we want to remove we can see why
-        // bellow.
+
         Node<E> before = head;
         for (int i = 1; i <= pos; i++) {
             before = before.next;
         }
         Node<E> destroy = before.next;
         E saved = destroy.value;
-        // assigning the next reference to the element following the element we want to remove...
-        // the last element will be assigned to the head.
-        before.next = before.next.next;
-        // scrubbing
+        before.next = destroy.next;
+
         if (destroy == tail) {
             tail = before;
         }

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

@@ -1,27 +1,26 @@
 package com.thealgorithms.datastructures.lists;
 
+/**
+ * CountSinglyLinkedListRecursion extends a singly linked list to include a
+ * recursive count method, which calculates the number of nodes in the list.
+ */
 public class CountSinglyLinkedListRecursion extends SinglyLinkedList {
 
-    public static void main(String[] args) {
-        CountSinglyLinkedListRecursion list = new CountSinglyLinkedListRecursion();
-        for (int i = 1; i <= 5; ++i) {
-            list.insert(i);
-        }
-        assert list.count() == 5;
-    }
-
     /**
-     * Calculate the count of the list manually using recursion.
+     * Recursively calculates the number of nodes in the list.
      *
-     * @param head head of the list.
-     * @return count of the list.
+     * @param head the head node of the list segment being counted.
+     * @return the count of nodes from the given head node onward.
      */
     private int countRecursion(Node head) {
         return head == null ? 0 : 1 + countRecursion(head.next);
     }
 
     /**
-     * Returns the count of the list.
+     * Returns the total number of nodes in the list by invoking the recursive
+     * count helper method.
+     *
+     * @return the total node count in the list.
      */
     @Override
     public int count() {

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;