Merge branch 'master' into feature/add-compression-algorithms

Author: DenizAltunkapan

pom.xml

@@ -82,7 +82,7 @@
             <plugin>
                 <groupId>org.jacoco</groupId>
                 <artifactId>jacoco-maven-plugin</artifactId>
-                <version>0.8.13</version>
+                <version>0.8.14</version>
                 <executions>
                     <execution>
                         <goals>
@@ -112,7 +112,7 @@
                     <dependency>
                     <groupId>com.puppycrawl.tools</groupId>
                     <artifactId>checkstyle</artifactId>
-                    <version>12.0.0</version>
+                    <version>12.0.1</version>
                     </dependency>
                 </dependencies>
             </plugin>

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

@@ -0,0 +1,92 @@
+package com.thealgorithms.datastructures.lists;
+/**
+ * Implements an algorithm to flatten a multilevel linked list.
+ *
+ * In this specific problem structure, each node has a `next` pointer (to the
+ * next node at the same level) and a `child` pointer (which points to the head
+ * of another sorted linked list). The goal is to merge all these lists into a
+ * single, vertically sorted linked list using the `child` pointer.
+ *
+ * The approach is a recursive one that leverages a merge utility, similar to
+ * the merge step in Merge Sort. It recursively flattens the list starting from
+ * the rightmost node and merges each node's child list with the already
+ * flattened list to its right.
+ * @see <a href="https://www.geeksforgeeks.org/flattening-a-linked-list/">GeeksforGeeks: Flattening a Linked List</a>
+ */
+public final class FlattenMultilevelLinkedList {
+    /**
+     * Private constructor to prevent instantiation of this utility class.
+     */
+    private FlattenMultilevelLinkedList() {
+    }
+    /**
+     * Node represents an element in the multilevel linked list. It contains the
+     * integer data, a reference to the next node at the same level, and a
+     * reference to the head of a child list.
+     */
+    static class Node {
+        int data;
+        Node next;
+        Node child;
+
+        Node(int data) {
+            this.data = data;
+            this.next = null;
+            this.child = null;
+        }
+    }
+
+    /**
+     * Merges two sorted linked lists (connected via the `child` pointer).
+     * This is a helper function for the main flatten algorithm.
+     *
+     * @param a The head of the first sorted list.
+     * @param b The head of the second sorted list.
+     * @return The head of the merged sorted list.
+     */
+    private static Node merge(Node a, Node b) {
+        // If one of the lists is empty, return the other.
+        if (a == null) {
+            return b;
+        }
+        if (b == null) {
+            return a;
+        }
+
+        Node result;
+
+        // Choose the smaller value as the new head.
+        if (a.data < b.data) {
+            result = a;
+            result.child = merge(a.child, b);
+        } else {
+            result = b;
+            result.child = merge(a, b.child);
+        }
+        result.next = null; // Ensure the merged list has no `next` pointers.
+        return result;
+    }
+
+    /**
+     * Flattens a multilevel linked list into a single sorted list.
+     * The flattened list is connected using the `child` pointers.
+     *
+     * @param head The head of the top-level list (connected via `next` pointers).
+     * @return The head of the fully flattened and sorted list.
+     */
+    public static Node flatten(Node head) {
+        // Base case: if the list is empty or has only one node, it's already flattened.
+        if (head == null || head.next == null) {
+            return head;
+        }
+
+        // Recursively flatten the list starting from the next node.
+        head.next = flatten(head.next);
+
+        // Now, merge the current list (head's child list) with the flattened rest of the list.
+        head = merge(head, head.next);
+
+        // Return the head of the fully merged list.
+        return head;
+    }
+}

src/main/java/com/thealgorithms/datastructures/lists/README.md

@@ -30,3 +30,4 @@ The `next` variable points to the next node in the data structure and value stor
 6. `MergeKSortedLinkedlist.java` : Merges K sorted linked list with mergesort (mergesort is also the most efficient sorting algorithm for linked list).
 7. `RandomNode.java` : Selects a random node from given linked list and diplays it.
 8. `SkipList.java` : Data Structure used for storing a sorted list of elements with help of a Linked list hierarchy that connects to subsequences of elements.
+9. `TortoiseHareAlgo.java` : Finds the middle element of a linked list using the fast and slow pointer (Tortoise-Hare) algorithm.

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

@@ -0,0 +1,63 @@
+package com.thealgorithms.datastructures.lists;
+
+public class TortoiseHareAlgo<E> {
+    static final class Node<E> {
+        Node<E> next;
+        E value;
+
+        private Node(E value, Node<E> next) {
+            this.value = value;
+            this.next = next;
+        }
+    }
+
+    private Node<E> head = null;
+
+    public TortoiseHareAlgo() {
+        head = null;
+    }
+
+    public void append(E value) {
+        Node<E> newNode = new Node<>(value, null);
+        if (head == null) {
+            head = newNode;
+            return;
+        }
+        Node<E> current = head;
+        while (current.next != null) {
+            current = current.next;
+        }
+        current.next = newNode;
+    }
+
+    public E getMiddle() {
+        if (head == null) {
+            return null;
+        }
+
+        Node<E> slow = head;
+        Node<E> fast = head;
+
+        while (fast != null && fast.next != null) {
+            slow = slow.next;
+            fast = fast.next.next;
+        }
+
+        return slow.value;
+    }
+
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder("[");
+        Node<E> current = head;
+        while (current != null) {
+            sb.append(current.value);
+            if (current.next != null) {
+                sb.append(", ");
+            }
+            current = current.next;
+        }
+        sb.append("]");
+        return sb.toString();
+    }
+}

src/main/java/com/thealgorithms/searches/SentinelLinearSearch.java

@@ -0,0 +1,99 @@
+package com.thealgorithms.searches;
+
+import com.thealgorithms.devutils.searches.SearchAlgorithm;
+
+/**
+ * Sentinel Linear Search is a variation of linear search that eliminates the
+ * need to check the array bounds in each iteration by placing the search key
+ * at the end of the array as a sentinel value.
+ *
+ * <p>
+ * The algorithm works by:
+ * 1. Storing the last element of the array
+ * 2. Placing the search key at the last position (sentinel)
+ * 3. Searching from the beginning without bound checking
+ * 4. If found before the last position, return the index
+ * 5. If found at the last position, check if it was originally there
+ *
+ * <p>
+ * Time Complexity:
+ * - Best case: O(1) - when the element is at the first position
+ * - Average case: O(n) - when the element is in the middle
+ * - Worst case: O(n) - when the element is not present
+ *
+ * <p>
+ * Space Complexity: O(1) - only uses constant extra space
+ *
+ * <p>
+ * Advantages over regular linear search:
+ * - Reduces the number of comparisons by eliminating bound checking
+ * - Slightly more efficient in practice due to fewer conditional checks
+ *
+ * @author TheAlgorithms Contributors
+ * @see LinearSearch
+ * @see SearchAlgorithm
+ */
+public class SentinelLinearSearch implements SearchAlgorithm {
+    /**
+     * Performs sentinel linear search on the given array.
+     *
+     * @param array the array to search in
+     * @param key the element to search for
+     * @param <T> the type of elements in the array, must be Comparable
+     * @return the index of the first occurrence of the key, or -1 if not found
+     * @throws IllegalArgumentException if the array is null
+     */
+    @Override
+    public <T extends Comparable<T>> int find(T[] array, T key) {
+        if (array == null) {
+            throw new IllegalArgumentException("Array cannot be null");
+        }
+
+        if (array.length == 0) {
+            return -1;
+        }
+
+        if (key == null) {
+            return findNull(array);
+        }
+
+        // Store the last element
+        T lastElement = array[array.length - 1];
+
+        // Place the sentinel (search key) at the end
+        array[array.length - 1] = key;
+
+        int i = 0;
+        // Search without bound checking since sentinel guarantees we'll find the key
+        while (array[i].compareTo(key) != 0) {
+            i++;
+        }
+
+        // Restore the original last element
+        array[array.length - 1] = lastElement;
+
+        // Check if we found the key before the sentinel position
+        // or if the original last element was the key we were looking for
+        if (i < array.length - 1 || (lastElement != null && lastElement.compareTo(key) == 0)) {
+            return i;
+        }
+
+        return -1; // Key not found
+    }
+
+    /**
+     * Helper method to find null values in the array.
+     *
+     * @param array the array to search in
+     * @param <T> the type of elements in the array
+     * @return the index of the first null element, or -1 if not found
+     */
+    private <T extends Comparable<T>> int findNull(T[] array) {
+        for (int i = 0; i < array.length; i++) {
+            if (array[i] == null) {
+                return i;
+            }
+        }
+        return -1;
+    }
+}

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

@@ -0,0 +1,112 @@
+package com.thealgorithms.datastructures.lists;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+import java.util.ArrayList;
+import java.util.List;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+/**
+ * Unit tests for the FlattenMultilevelLinkedList class.
+ * This class tests the flattening logic with various list structures,
+ * including null lists, simple lists, and complex multilevel lists.
+ */
+final class FlattenMultilevelLinkedListTest {
+
+    // A helper function to convert a flattened list (connected by child pointers)
+    // into a standard Java List for easy comparison.
+    private List<Integer> toList(FlattenMultilevelLinkedList.Node head) {
+        List<Integer> list = new ArrayList<>();
+        FlattenMultilevelLinkedList.Node current = head;
+        while (current != null) {
+            list.add(current.data);
+            current = current.child;
+        }
+        return list;
+    }
+
+    @Test
+    @DisplayName("Test with a null list")
+    void testFlattenNullList() {
+        assertNull(FlattenMultilevelLinkedList.flatten(null));
+    }
+
+    @Test
+    @DisplayName("Test with a simple, single-level list")
+    void testFlattenSingleLevelList() {
+        // Create a simple list: 1 -> 2 -> 3
+        FlattenMultilevelLinkedList.Node head = new FlattenMultilevelLinkedList.Node(1);
+        head.next = new FlattenMultilevelLinkedList.Node(2);
+        head.next.next = new FlattenMultilevelLinkedList.Node(3);
+
+        // Flatten the list
+        FlattenMultilevelLinkedList.Node flattenedHead = FlattenMultilevelLinkedList.flatten(head);
+
+        // Expected output: 1 -> 2 -> 3 (vertically)
+        List<Integer> expected = List.of(1, 2, 3);
+        assertEquals(expected, toList(flattenedHead));
+    }
+
+    @Test
+    @DisplayName("Test with a complex multilevel list")
+    void testFlattenComplexMultilevelList() {
+        // Create the multilevel structure from the problem description
+        // 5 -> 10 -> 19 -> 28
+        // |    |     |     |
+        // 7    20    22    35
+        // |          |     |
+        // 8          50    40
+        // |                |
+        // 30               45
+        FlattenMultilevelLinkedList.Node head = new FlattenMultilevelLinkedList.Node(5);
+        head.child = new FlattenMultilevelLinkedList.Node(7);
+        head.child.child = new FlattenMultilevelLinkedList.Node(8);
+        head.child.child.child = new FlattenMultilevelLinkedList.Node(30);
+
+        head.next = new FlattenMultilevelLinkedList.Node(10);
+        head.next.child = new FlattenMultilevelLinkedList.Node(20);
+
+        head.next.next = new FlattenMultilevelLinkedList.Node(19);
+        head.next.next.child = new FlattenMultilevelLinkedList.Node(22);
+        head.next.next.child.child = new FlattenMultilevelLinkedList.Node(50);
+
+        head.next.next.next = new FlattenMultilevelLinkedList.Node(28);
+        head.next.next.next.child = new FlattenMultilevelLinkedList.Node(35);
+        head.next.next.next.child.child = new FlattenMultilevelLinkedList.Node(40);
+        head.next.next.next.child.child.child = new FlattenMultilevelLinkedList.Node(45);
+
+        // Flatten the list
+        FlattenMultilevelLinkedList.Node flattenedHead = FlattenMultilevelLinkedList.flatten(head);
+
+        // Expected sorted output
+        List<Integer> expected = List.of(5, 7, 8, 10, 19, 20, 22, 28, 30, 35, 40, 45, 50);
+        assertEquals(expected, toList(flattenedHead));
+    }
+
+    @Test
+    @DisplayName("Test with some empty child lists")
+    void testFlattenWithEmptyChildLists() {
+        // Create a list: 5 -> 10 -> 12
+        // |           |
+        // 7           11
+        // |
+        // 9
+        FlattenMultilevelLinkedList.Node head = new FlattenMultilevelLinkedList.Node(5);
+        head.child = new FlattenMultilevelLinkedList.Node(7);
+        head.child.child = new FlattenMultilevelLinkedList.Node(9);
+
+        head.next = new FlattenMultilevelLinkedList.Node(10); // No child list
+        head.next.child = null;
+
+        head.next.next = new FlattenMultilevelLinkedList.Node(12);
+        head.next.next.child = new FlattenMultilevelLinkedList.Node(16);
+
+        // Flatten the list
+        FlattenMultilevelLinkedList.Node flattenedHead = FlattenMultilevelLinkedList.flatten(head);
+
+        // Expected sorted output
+        List<Integer> expected = List.of(5, 7, 9, 10, 12, 16);
+        assertEquals(expected, toList(flattenedHead));
+    }
+}