Add Tim sort implementation with tests

Hybrid merge sort + insertion sort: splits array into runs of 32,
sorts each with insertion sort, then iteratively merges. Stable,
O(n log n) worst case, O(n) best case. Implements InplaceSort and
is integrated into the shared SortingTest.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: williamfiset

README.md

@@ -283,6 +283,7 @@ $ java -cp classes com.williamfiset.algorithms.search.BinarySearch
 - [Quicksort (in-place, Hoare partitioning)](src/main/java/com/williamfiset/algorithms/sorting/QuickSort.java) **- Θ(nlog(n))**
 - [Quicksort3 (Dutch National Flag algorithm)](src/main/java/com/williamfiset/algorithms/sorting/QuickSort3.java) **- Θ(nlog(n))**
 - [Selection sort](src/main/java/com/williamfiset/algorithms/sorting/SelectionSort.java) **- O(n<sup>2</sup>)**
+- [Tim sort](src/main/java/com/williamfiset/algorithms/sorting/TimSort.java) **- O(nlog(n))**
 - [Radix sort](src/main/java/com/williamfiset/algorithms/sorting/RadixSort.java) **- O(n\*w)**
 
 # String algorithms

src/main/java/com/williamfiset/algorithms/sorting/BUILD

@@ -77,6 +77,13 @@ java_binary(
     runtime_deps = [":sorting"],
 )
 
+# bazel run //src/main/java/com/williamfiset/algorithms/sorting:TimSort
+java_binary(
+    name = "TimSort",
+    main_class = "com.williamfiset.algorithms.sorting.TimSort",
+    runtime_deps = [":sorting"],
+)
+
 # bazel run //src/main/java/com/williamfiset/algorithms/sorting:SelectionSort
 java_binary(
     name = "SelectionSort",

src/main/java/com/williamfiset/algorithms/sorting/TimSort.java

@@ -0,0 +1,90 @@
+/**
+ * Tim sort implementation — a hybrid sorting algorithm combining merge sort and insertion sort.
+ *
+ * Tim sort divides the array into small chunks called "runs" and sorts each run using insertion
+ * sort (which is efficient for small or nearly-sorted data). It then merges the runs using a
+ * merge step similar to merge sort. This is the algorithm used by Java's Arrays.sort() for objects
+ * and Python's built-in sort.
+ *
+ * Time Complexity: O(n log n) worst case, O(n) best case (already sorted)
+ * Space Complexity: O(n) for the merge buffer
+ *
+ * @author Claude
+ */
+package com.williamfiset.algorithms.sorting;
+
+public class TimSort implements InplaceSort {
+
+  private static final int MIN_RUN = 32;
+
+  @Override
+  public void sort(int[] values) {
+    timSort(values);
+  }
+
+  public static void timSort(int[] ar) {
+    if (ar == null || ar.length <= 1)
+      return;
+
+    int n = ar.length;
+
+    // Sort individual runs using insertion sort
+    for (int i = 0; i < n; i += MIN_RUN)
+      insertionSort(ar, i, Math.min(i + MIN_RUN - 1, n - 1));
+
+    // Merge runs, doubling the merge size each iteration
+    for (int size = MIN_RUN; size < n; size *= 2) {
+      for (int left = 0; left < n; left += 2 * size) {
+        int mid = Math.min(left + size - 1, n - 1);
+        int right = Math.min(left + 2 * size - 1, n - 1);
+        if (mid < right)
+          merge(ar, left, mid, right);
+      }
+    }
+  }
+
+  /** Insertion sort on ar[lo..hi] inclusive. */
+  private static void insertionSort(int[] ar, int lo, int hi) {
+    for (int i = lo + 1; i <= hi; i++) {
+      int key = ar[i];
+      int j = i - 1;
+      while (j >= lo && ar[j] > key) {
+        ar[j + 1] = ar[j];
+        j--;
+      }
+      ar[j + 1] = key;
+    }
+  }
+
+  /** Merges two sorted sub-arrays ar[lo..mid] and ar[mid+1..hi]. */
+  private static void merge(int[] ar, int lo, int mid, int hi) {
+    int len1 = mid - lo + 1;
+    int len2 = hi - mid;
+
+    int[] left = new int[len1];
+    int[] right = new int[len2];
+    System.arraycopy(ar, lo, left, 0, len1);
+    System.arraycopy(ar, mid + 1, right, 0, len2);
+
+    int i = 0, j = 0, k = lo;
+    while (i < len1 && j < len2) {
+      // Use <= to maintain stability: equal elements from the left run come first
+      if (left[i] <= right[j])
+        ar[k++] = left[i++];
+      else
+        ar[k++] = right[j++];
+    }
+    while (i < len1)
+      ar[k++] = left[i++];
+    while (j < len2)
+      ar[k++] = right[j++];
+  }
+
+  public static void main(String[] args) {
+    int[] array = {10, 4, 6, 4, 8, -13, 2, 3};
+    timSort(array);
+    // Prints:
+    // [-13, 2, 3, 4, 4, 6, 8, 10]
+    System.out.println(java.util.Arrays.toString(array));
+  }
+}

src/test/java/com/williamfiset/algorithms/sorting/BUILD

@@ -127,6 +127,16 @@ java_test(
     deps = TEST_DEPS,
 )
 
+java_test(
+    name = "TimSortTest",
+    srcs = ["TimSortTest.java"],
+    main_class = "org.junit.platform.console.ConsoleLauncher",
+    use_testrunner = False,
+    args = ["--select-class=com.williamfiset.algorithms.sorting.TimSortTest"],
+    runtime_deps = JUNIT5_RUNTIME_DEPS,
+    deps = TEST_DEPS,
+)
+
 java_test(
     name = "SortingTest",
     srcs = ["SortingTest.java"],

src/test/java/com/williamfiset/algorithms/sorting/SortingTest.java

@@ -25,7 +25,8 @@ enum SortingAlgorithm {
     QUICK_SORT(new QuickSort()),
     QUICK_SORT3(new QuickSort3()),
     RADIX_SORT(new RadixSort()),
-    SELECTION_SORT(new SelectionSort());
+    SELECTION_SORT(new SelectionSort()),
+    TIM_SORT(new TimSort());
 
     private InplaceSort algorithm;
 
@@ -49,7 +50,8 @@ public InplaceSort getSortingAlgorithm() {
           SortingAlgorithm.QUICK_SORT,
           SortingAlgorithm.QUICK_SORT3,
           SortingAlgorithm.RADIX_SORT,
-          SortingAlgorithm.SELECTION_SORT);
+          SortingAlgorithm.SELECTION_SORT,
+          SortingAlgorithm.TIM_SORT);
 
   @Test
   public void verifySortingAlgorithms_smallPositiveIntegersOnly() {

src/test/java/com/williamfiset/algorithms/sorting/TimSortTest.java

@@ -0,0 +1,103 @@
+package com.williamfiset.algorithms.sorting;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import com.williamfiset.algorithms.utils.TestUtils;
+import java.util.Arrays;
+import org.junit.jupiter.api.*;
+
+public class TimSortTest {
+
+  private final TimSort sorter = new TimSort();
+
+  @Test
+  public void testEmptyArray() {
+    int[] array = {};
+    sorter.sort(array);
+    assertThat(array).isEqualTo(new int[] {});
+  }
+
+  @Test
+  public void testSingleElement() {
+    int[] array = {42};
+    sorter.sort(array);
+    assertThat(array).isEqualTo(new int[] {42});
+  }
+
+  @Test
+  public void testAlreadySorted() {
+    int[] array = {1, 2, 3, 4, 5};
+    sorter.sort(array);
+    assertThat(array).isEqualTo(new int[] {1, 2, 3, 4, 5});
+  }
+
+  @Test
+  public void testReverseSorted() {
+    int[] array = {5, 4, 3, 2, 1};
+    sorter.sort(array);
+    assertThat(array).isEqualTo(new int[] {1, 2, 3, 4, 5});
+  }
+
+  @Test
+  public void testWithDuplicates() {
+    int[] array = {10, 4, 6, 4, 8, -13, 2, 3};
+    sorter.sort(array);
+    assertThat(array).isEqualTo(new int[] {-13, 2, 3, 4, 4, 6, 8, 10});
+  }
+
+  @Test
+  public void testAllSameElements() {
+    int[] array = {3, 3, 3, 3, 3};
+    sorter.sort(array);
+    assertThat(array).isEqualTo(new int[] {3, 3, 3, 3, 3});
+  }
+
+  @Test
+  public void testNegativeNumbers() {
+    int[] array = {-3, -1, -4, -1, -5};
+    sorter.sort(array);
+    assertThat(array).isEqualTo(new int[] {-5, -4, -3, -1, -1});
+  }
+
+  @Test
+  public void testMixedPositiveAndNegative() {
+    int[] array = {3, -2, 0, 7, -5, 1};
+    sorter.sort(array);
+    assertThat(array).isEqualTo(new int[] {-5, -2, 0, 1, 3, 7});
+  }
+
+  @Test
+  public void testTwoElements() {
+    int[] array = {9, 1};
+    sorter.sort(array);
+    assertThat(array).isEqualTo(new int[] {1, 9});
+  }
+
+  @Test
+  public void testSmallerThanMinRun() {
+    int[] array = {5, 3, 8, 1, 9, 2, 7};
+    sorter.sort(array);
+    assertThat(array).isEqualTo(new int[] {1, 2, 3, 5, 7, 8, 9});
+  }
+
+  @Test
+  public void testLargerThanMinRun() {
+    // 100 elements to exercise the merge phase
+    int[] array = TestUtils.randomIntegerArray(100, -50, 51);
+    int[] expected = array.clone();
+    Arrays.sort(expected);
+    sorter.sort(array);
+    assertThat(array).isEqualTo(expected);
+  }
+
+  @Test
+  public void testRandomized() {
+    for (int size = 0; size < 500; size++) {
+      int[] values = TestUtils.randomIntegerArray(size, -50, 51);
+      int[] expected = values.clone();
+      Arrays.sort(expected);
+      sorter.sort(values);
+      assertThat(values).isEqualTo(expected);
+    }
+  }
+}