major: adding the missing algorithm

Author: Rosander0

src/main/java/com/thealgorithms/sorts/LibrarySort.java

@@ -1,11 +1,15 @@
 package com.thealgorithms.sorts;
 
+import java.util.Arrays;
+
 /**
- * Library Sort (also known as Gapped Insertion Sort) is traditionally implemented
- * using periodic gaps between elements for faster insertion. This implementation
- * uses binary search to find the insertion position combined with array shifting,
- * which is a simplified variant without gap-based optimization.
- * Time Complexity: O(n^2) worst case due to element shifting
+ * Library Sort (also known as Gapped Insertion Sort) maintains a sparse
+ * working array with gaps distributed between elements, so that most
+ * insertions land directly in an empty gap without shifting anything.
+ * Elements are inserted in rounds that double in size (1, 2, 4, 8, ...);
+ * after each round the array is rebalanced so gaps are spread out evenly
+ * again for the next round.
+ * Time Complexity: O(n log n) expected, O(n^2) worst case if gaps collapse
  * Space Complexity: O(n)
  *
  * @see <a href="https://en.wikipedia.org/wiki/Library_sort">
@@ -14,6 +18,8 @@
  */
 public final class LibrarySort {
 
+    private static final int GAP_FACTOR = 2;
+
     private LibrarySort() {
         // Utility class
     }
@@ -33,49 +39,169 @@ public static int[] sort(final int[] array) {
             return array;
         }
 
-        int n = array.length;
-        Integer[] spaced = new Integer[2 * n];
+        final int n = array.length;
+        final int capacity = GAP_FACTOR * n;
+        final int[] data = new int[capacity];
+        final boolean[] occupied = new boolean[capacity];
 
-        spaced[0] = array[0];
-        int inserted = 1;
+        final int mid = capacity / 2;
+        data[mid] = array[0];
+        occupied[mid] = true;
 
-        for (int i = 1; i < n; i++) {
-            int pos = binarySearch(spaced, inserted, array[i]);
-            for (int j = inserted; j > pos; j--) {
-                spaced[j] = spaced[j - 1];
+        int filled = 1;
+        int nextToInsert = 1;
+        int round = 0;
+        while (nextToInsert < n) {
+            final int roundSize = Math.min(1 << round, n - nextToInsert);
+            for (int i = 0; i < roundSize; i++) {
+                insert(data, occupied, array[nextToInsert + i]);
+                filled++;
+            }
+            nextToInsert += roundSize;
+            round++;
+            if (nextToInsert < n) {
+                rebalance(data, occupied, filled);
             }
-            spaced[pos] = array[i];
-            inserted++;
         }
 
         int idx = 0;
-        for (int i = 0; i < 2 * n; i++) {
-            if (spaced[i] != null) {
-                array[idx++] = spaced[i];
+        for (int i = 0; i < capacity; i++) {
+            if (occupied[i]) {
+                array[idx++] = data[i];
             }
         }
         return array;
     }
 
     /**
-     * Binary search to find insertion position among inserted elements.
-     *
-     * @param spaced the spaced array
-     * @param inserted number of elements inserted so far
-     * @param target the value to find position for
-     * @return the correct insertion index
+     * Inserts {@code value} into the gapped array, placing it directly in an
+     * empty gap when possible, otherwise shifting toward the nearest gap.
+     */
+    private static void insert(final int[] data, final boolean[] occupied, final int value) {
+        final int pos = findInsertionIndex(data, occupied, value);
+        if (pos >= data.length) {
+            insertAtEnd(data, occupied, value);
+            return;
+        }
+
+        if (!occupied[pos]) {
+            data[pos] = value;
+            occupied[pos] = true;
+            return;
+        }
+
+        int right = pos;
+        while (right < data.length && occupied[right]) {
+            right++;
+        }
+        int left = pos - 1;
+        while (left >= 0 && occupied[left]) {
+            left--;
+        }
+
+        final boolean canGoRight = right < data.length;
+        final boolean canGoLeft = left >= 0;
+
+        if (canGoRight && (!canGoLeft || (right - pos) <= (pos - left))) {
+            // Shift data[pos, right) one slot to the right, opening a gap at pos.
+            // occupied[pos] is untouched by the copy and was already true.
+            System.arraycopy(data, pos, data, pos + 1, right - pos);
+            occupied[right] = true;
+            data[pos] = value;
+        } else if (canGoLeft) {
+            // Shift data[left + 1, pos) one slot to the left, opening a gap at pos - 1.
+            // occupied[pos - 1] is untouched by the copy and was already true.
+            System.arraycopy(data, left + 1, data, left, pos - 1 - left);
+            occupied[left] = true;
+            data[pos - 1] = value;
+        } else {
+            // Unreachable in practice: canGoRight and canGoLeft can only both be false if
+            // every slot in this capacity-2n array is occupied, but at most n elements are
+            // ever present at once. Kept as a defensive guard against that invariant breaking.
+            throw new IllegalStateException("No gap available for insertion; rebalance too infrequent.");
+        }
+    }
+
+    /**
+     * Handles insertion of a new global maximum, which must land after every
+     * currently occupied slot. Since there is no room to its right, this
+     * shifts occupied slots left into the nearest gap instead.
+     */
+    private static void insertAtEnd(final int[] data, final boolean[] occupied, final int value) {
+        final int last = data.length - 1;
+        // occupied[last] is unreachable as false here: insertAtEnd() is only called when
+        // findInsertionIndex() returns data.length, which requires data[last] to already be
+        // occupied. Kept as a defensive guard in case that invariant is ever broken.
+        if (!occupied[last]) {
+            data[last] = value;
+            occupied[last] = true;
+            return;
+        }
+        int left = last - 1;
+        while (left >= 0 && occupied[left]) {
+            left--;
+        }
+        // left < 0 is unreachable in practice: at most n elements ever occupy this
+        // capacity-2n array, so fewer than half the slots left of `last` can be filled,
+        // guaranteeing a gap exists before the scan reaches index -1.
+        if (left < 0) {
+            throw new IllegalStateException("No gap available for insertion; rebalance too infrequent.");
+        }
+        // Shift data[left + 1, last] one slot to the left, opening a gap at last.
+        // occupied[last] is untouched by the copy and was already true.
+        System.arraycopy(data, left + 1, data, left, last - left);
+        occupied[left] = true;
+        data[last] = value;
+    }
+
+    /**
+     * Finds the leftmost index at which {@code value} can be inserted so
+     * that occupied slots remain sorted. Empty slots are compared using the
+     * value of the nearest occupied slot at or after them, which is a
+     * monotonic function of index and therefore safe to binary search over.
      */
-    private static int binarySearch(final Integer[] spaced, final int inserted, final int target) {
+    private static int findInsertionIndex(final int[] data, final boolean[] occupied, final int value) {
         int lo = 0;
-        int hi = inserted;
+        int hi = data.length;
         while (lo < hi) {
-            int mid = lo + (hi - lo) / 2;
-            if (spaced[mid] <= target) {
+            final int mid = lo + (hi - lo) / 2;
+            final int probe = nearestOccupiedValueAtOrAfter(data, occupied, mid);
+            if (probe != Integer.MAX_VALUE && probe <= value) {
                 lo = mid + 1;
             } else {
                 hi = mid;
             }
         }
         return lo;
     }
+
+    private static int nearestOccupiedValueAtOrAfter(final int[] data, final boolean[] occupied, final int index) {
+        for (int i = index; i < data.length; i++) {
+            if (occupied[i]) {
+                return data[i];
+            }
+        }
+        return Integer.MAX_VALUE;
+    }
+
+    /**
+     * Redistributes the {@code filled} occupied elements evenly across the
+     * full capacity of {@code data}, restoring uniform gaps between them.
+     */
+    private static void rebalance(final int[] data, final boolean[] occupied, final int filled) {
+        final int capacity = data.length;
+        final int[] temp = new int[filled];
+        int idx = 0;
+        for (int i = 0; i < capacity; i++) {
+            if (occupied[i]) {
+                temp[idx++] = data[i];
+            }
+        }
+        Arrays.fill(occupied, false);
+        for (int k = 0; k < filled; k++) {
+            final int pos = (int) ((long) k * capacity / filled);
+            data[pos] = temp[k];
+            occupied[pos] = true;
+        }
+    }
 }

src/test/java/com/thealgorithms/sorts/LibrarySortTest.java

@@ -1,5 +1,4 @@
 package com.thealgorithms.sorts;
-// author: Vraj Prajapati @Rosander0
 
 import static org.junit.jupiter.api.Assertions.assertArrayEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
@@ -42,4 +41,30 @@ public void testEmptyArray() {
     public void testNullArray() {
         assertThrows(IllegalArgumentException.class, () -> LibrarySort.sort(null));
     }
+
+    // --- Added to cover branches the tests above never reach ---
+
+    @Test
+    public void testShiftLeftWhenRightSideIsFull() {
+        // Right side of the target slot is completely occupied, forcing a left shift.
+        assertArrayEquals(new int[] {0, 1, 2, 3, 4, 5, 6}, LibrarySort.sort(new int[] {0, 1, 2, 6, 4, 5, 3}));
+    }
+
+    @Test
+    public void testTieBreakPrefersRightWhenDistancesEqual() {
+        // A gap exists on both sides at equal distance; algorithm should favor the right shift.
+        assertArrayEquals(new int[] {0, 1, 2, 3}, LibrarySort.sort(new int[] {0, 1, 3, 2}));
+    }
+
+    @Test
+    public void testRightSearchRunsOffTheEnd() {
+        // No gap anywhere to the right of the target slot, all the way to the array's end.
+        assertArrayEquals(new int[] {0, 1, 2, 3, 4, 5, 6, 7}, LibrarySort.sort(new int[] {0, 1, 2, 3, 4, 5, 7, 6}));
+    }
+
+    @Test
+    public void testInsertAtEndWithNoTrailingGap() {
+        // A new global maximum arrives with no trailing gap left, forcing insertAtEnd().
+        assertArrayEquals(new int[] {0, 1, 2, 3, 4, 5, 6, 7}, LibrarySort.sort(new int[] {0, 1, 2, 3, 4, 5, 6, 7}));
+    }
 }