refactor: Enhance docs, add tests in RotateSinglyLinkedLists

Author: Hardvan

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

@@ -1,11 +1,43 @@
 package com.thealgorithms.datastructures.lists;
 
 /**
- * Rotate a list
- * @author Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
+ * The RotateSinglyLinkedLists class provides a method to rotate a singly linked list
+ * to the right by a specified number of positions.
+ * <p>
+ * In a right rotation by `k` steps, each node in the list moves `k` positions to the right.
+ * Nodes that are rotated off the end of the list are placed back at the beginning.
+ * </p>
+ * <p>
+ * Example:
+ * Given linked list: 1 -> 2 -> 3 -> 4 -> 5 and k = 2, the output will be:
+ * 4 -> 5 -> 1 -> 2 -> 3.
+ * </p>
+ * <p>
+ * Edge Cases:
+ * <ul>
+ *   <li>If the list is empty, returns null.</li>
+ *   <li>If `k` is 0 or a multiple of the list length, the list remains unchanged.</li>
+ * </ul>
+ * </p>
+ * <p>
+ * Complexity:
+ * <ul>
+ *   <li>Time Complexity: O(n), where n is the number of nodes in the linked list.</li>
+ *   <li>Space Complexity: O(1), as we only use a constant amount of additional space.</li>
+ * </ul>
+ * </p>
+ *
+ * Author: Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
  */
-
 public class RotateSinglyLinkedLists {
+
+    /**
+     * Rotates a singly linked list to the right by `k` positions.
+     *
+     * @param head The head node of the singly linked list.
+     * @param k The number of positions to rotate the list to the right.
+     * @return The head of the rotated linked list.
+     */
     public Node rotateRight(Node head, int k) {
         if (head == null || head.next == null || k == 0) {
             return head;

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

@@ -6,67 +6,99 @@
 import org.junit.jupiter.api.Test;
 
 /**
- * Test cases for RotateSinglyLinkedLists
+ * Test cases for RotateSinglyLinkedLists.
  * Author: Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
  */
 public class RotateSinglyLinkedListsTest {
 
+    private final RotateSinglyLinkedLists rotator = new RotateSinglyLinkedLists();
+
+    // Helper method to create a linked list from an array of values
+    private Node createLinkedList(int[] values) {
+        if (values.length == 0) return null;
+
+        Node head = new Node(values[0]);
+        Node current = head;
+        for (int i = 1; i < values.length; i++) {
+            current.next = new Node(values[i]);
+            current = current.next;
+        }
+        return head;
+    }
+
+    // Helper method to convert a linked list to a string for easy comparison
+    private String linkedListToString(Node head) {
+        StringBuilder sb = new StringBuilder();
+        Node current = head;
+        while (current != null) {
+            sb.append(current.value);
+            if (current.next != null) {
+                sb.append(" -> ");
+            }
+            current = current.next;
+        }
+        return sb.toString();
+    }
+
     @Test
     public void testRotateRightEmptyList() {
-        RotateSinglyLinkedLists rotator = new RotateSinglyLinkedLists();
-
-        // Test case: Rotate an empty list
+        // Rotate an empty list
         assertNull(rotator.rotateRight(null, 2));
     }
 
     @Test
     public void testRotateRightSingleNodeList() {
-        RotateSinglyLinkedLists rotator = new RotateSinglyLinkedLists();
-
-        // Test case: Rotate a list with one element
+        // Rotate a list with a single element
         Node singleNode = new Node(5);
         Node rotatedSingleNode = rotator.rotateRight(singleNode, 3);
-        assertEquals(5, rotatedSingleNode.value);
-        assertNull(rotatedSingleNode.next);
+        assertEquals("5", linkedListToString(rotatedSingleNode));
     }
 
     @Test
     public void testRotateRightMultipleElementsList() {
-        RotateSinglyLinkedLists rotator = new RotateSinglyLinkedLists();
+        // Rotate a list with multiple elements (rotate by 2)
+        Node head = createLinkedList(new int[] {1, 2, 3, 4, 5});
+        Node rotated = rotator.rotateRight(head, 2);
+        assertEquals("4 -> 5 -> 1 -> 2 -> 3", linkedListToString(rotated));
+    }
 
-        // Test case: Rotate a list with multiple elements (Rotate by 2)
-        Node head = new Node(1);
-        head.next = new Node(2);
-        head.next.next = new Node(3);
-        head.next.next.next = new Node(4);
-        head.next.next.next.next = new Node(5);
+    @Test
+    public void testRotateRightFullRotation() {
+        // Rotate by more than the length of the list
+        Node head = createLinkedList(new int[] {1, 2, 3, 4, 5});
+        Node rotated = rotator.rotateRight(head, 7);
+        assertEquals("4 -> 5 -> 1 -> 2 -> 3", linkedListToString(rotated));
+    }
 
-        Node rotated1 = rotator.rotateRight(head, 2);
-        assertEquals(4, rotated1.value);
-        assertEquals(5, rotated1.next.value);
-        assertEquals(1, rotated1.next.next.value);
-        assertEquals(2, rotated1.next.next.next.value);
-        assertEquals(3, rotated1.next.next.next.next.value);
-        assertNull(rotated1.next.next.next.next.next);
+    @Test
+    public void testRotateRightZeroRotation() {
+        // Rotate a list by k = 0 (no rotation)
+        Node head = createLinkedList(new int[] {1, 2, 3, 4, 5});
+        Node rotated = rotator.rotateRight(head, 0);
+        assertEquals("1 -> 2 -> 3 -> 4 -> 5", linkedListToString(rotated));
     }
 
     @Test
-    public void testRotateRightFullRotation() {
-        RotateSinglyLinkedLists rotator = new RotateSinglyLinkedLists();
+    public void testRotateRightByListLength() {
+        // Rotate a list by k equal to list length (no change)
+        Node head = createLinkedList(new int[] {1, 2, 3, 4, 5});
+        Node rotated = rotator.rotateRight(head, 5);
+        assertEquals("1 -> 2 -> 3 -> 4 -> 5", linkedListToString(rotated));
+    }
 
-        // Test case: Rotate a list with multiple elements (Full rotation)
-        Node head = new Node(1);
-        head.next = new Node(2);
-        head.next.next = new Node(3);
-        head.next.next.next = new Node(4);
-        head.next.next.next.next = new Node(5);
+    @Test
+    public void testRotateRightByMultipleOfListLength() {
+        // Rotate a list by a multiple of its length (no change)
+        Node head = createLinkedList(new int[] {1, 2, 3, 4, 5});
+        Node rotated = rotator.rotateRight(head, 10); // k = 2 * list length
+        assertEquals("1 -> 2 -> 3 -> 4 -> 5", linkedListToString(rotated));
+    }
 
-        Node rotated3 = rotator.rotateRight(head, 7);
-        assertEquals(4, rotated3.value);
-        assertEquals(5, rotated3.next.value);
-        assertEquals(1, rotated3.next.next.value);
-        assertEquals(2, rotated3.next.next.next.value);
-        assertEquals(3, rotated3.next.next.next.next.value);
-        assertNull(rotated3.next.next.next.next.next);
+    @Test
+    public void testRotateRightLongerList() {
+        // Rotate a longer list by a smaller k
+        Node head = createLinkedList(new int[] {1, 2, 3, 4, 5, 6, 7, 8, 9});
+        Node rotated = rotator.rotateRight(head, 4);
+        assertEquals("6 -> 7 -> 8 -> 9 -> 1 -> 2 -> 3 -> 4 -> 5", linkedListToString(rotated));
     }
 }