array-sort 0.1.1 → 1.0.0

data/lib/array_sort/algorithms/cycle_sort.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Cycle sort: writes every element directly into its final position, following the cycles of the permutation.
+  #
+  # An element's final position is found by counting how many elements are smaller than it. Each element is written
+  # at most once, so the number of writes is the theoretical minimum, at the cost of O(n²) comparisons.
+  #
+  # @api private
+  module CycleSort
+    module_function
+
+    def call(array, compare)
+      length = array.length
+      # With a consistent comparison every element is written at most once, so the whole sort makes at most +length+
+      # writes. The budget only matters for inconsistent comparisons, where it keeps the sort O(n²); running out
+      # closes the current cycle by putting +item+ back at +start+, so no element is ever lost.
+      writes_left = length
+      (0...(length - 1)).each do |start|
+        item = array[start]
+        position = position_of(array, compare, item, start)
+        next if position == start
+
+        loop do
+          position += 1 while position < length && compare.call(item, array[position]).zero?
+          position = start if position >= length || (writes_left -= 1).negative?
+          array[position], item = item, array[position]
+          break if position == start
+
+          position = position_of(array, compare, item, start)
+        end
+      end
+      array
+    end
+
+    # Returns where +item+ belongs: +start+ plus the number of elements after +start+ that are smaller than it.
+    def position_of(array, compare, item, start)
+      position = start
+      ((start + 1)...array.length).each { |i| position += 1 if compare.call(array[i], item).negative? }
+      position
+    end
+  end
+
+  register :cycle, CycleSort, title: 'Cycle sort', stable: false,
+                              best: 'n²', average: 'n²', worst: 'n²', space: '1'
+end

data/lib/array_sort/algorithms/gnome_sort.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Gnome sort: a garden gnome walks along a line of flower pots, swapping each pot backwards while it is smaller than
+  # the one before it, then returning to where it left off.
+  #
+  # This is the common variant where the gnome remembers its position instead of walking back step by step, which
+  # also guarantees it finishes even if the comparison is inconsistent.
+  #
+  # @api private
+  module GnomeSort
+    module_function
+
+    def call(array, compare)
+      (1...array.length).each do |position|
+        i = position
+        while i.positive? && compare.call(array[i - 1], array[i]).positive?
+          array[i - 1], array[i] = array[i], array[i - 1]
+          i -= 1
+        end
+      end
+      array
+    end
+  end
+
+  register :gnome, GnomeSort, title: 'Gnome sort', stable: true,
+                              best: 'n', average: 'n²', worst: 'n²', space: '1'
+end

data/lib/array_sort/algorithms/heap_sort.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Heap sort: builds a max-heap in place, then repeatedly swaps the largest element to the end of the unsorted region
+  # and restores the heap over what remains.
+  #
+  # @api private
+  module HeapSort
+    module_function
+
+    def call(array, compare)
+      sort_range(array, compare, 0, array.length - 1)
+      array
+    end
+
+    # Sorts +array[low..high]+. Heap positions are counted from +low+, so the heap's root is +array[low]+.
+    def sort_range(array, compare, low, high)
+      last = high - low
+      ((last - 1) / 2).downto(0) { |root| sift_down(array, compare, low, root, last) }
+      last.downto(1) do |boundary|
+        array[low], array[low + boundary] = array[low + boundary], array[low]
+        sift_down(array, compare, low, 0, boundary - 1)
+      end
+    end
+
+    # Moves the element at heap position +root+ down until neither child (up to position +last+) is larger than it.
+    def sift_down(array, compare, base, root, last)
+      loop do
+        child = (root * 2) + 1
+        break if child > last
+
+        child += 1 if child < last && compare.call(array[base + child], array[base + child + 1]).negative?
+        break unless compare.call(array[base + root], array[base + child]).negative?
+
+        array[base + root], array[base + child] = array[base + child], array[base + root]
+        root = child
+      end
+    end
+  end
+
+  register :heap, HeapSort, title: 'Heap sort', stable: false,
+                            best: 'n log n', average: 'n log n', worst: 'n log n', space: '1'
+end

data/lib/array_sort/algorithms/insertion_sort.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Insertion sort: grows a sorted prefix one element at a time, inserting each new element where it belongs.
+  #
+  # Larger elements are shifted one slot to the right until the gap reaches the correct position, which takes fewer
+  # writes than swapping the element into place pair by pair. Very fast on small or nearly-sorted arrays, which is why
+  # hybrid sorts like introsort use it for short ranges.
+  #
+  # @api private
+  module InsertionSort
+    module_function
+
+    def call(array, compare)
+      sort_range(array, compare, 0, array.length - 1)
+      array
+    end
+
+    # Sorts +array[low..high]+.
+    def sort_range(array, compare, low, high)
+      ((low + 1)..high).each do |i|
+        element = array[i]
+        j = i
+        while j > low && compare.call(array[j - 1], element).positive?
+          array[j] = array[j - 1]
+          j -= 1
+        end
+        array[j] = element unless j == i
+      end
+    end
+  end
+
+  register :insertion, InsertionSort, title: 'Insertion sort', stable: true,
+                                      best: 'n', average: 'n²', worst: 'n²', space: '1'
+end

data/lib/array_sort/algorithms/intro_sort.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Introsort: quicksort that switches to heap sort if the recursion gets too deep, and to insertion sort for short
+  # ranges. This is the algorithm behind C++'s std::sort.
+  #
+  # Quicksort is fastest in practice; the heap sort fallback caps the worst case at O(n log n), and insertion sort
+  # is faster than either on a handful of elements. Sorted and reversed input partition perfectly; "organ pipe" input
+  # (ascending, then descending) is a classic case where median-of-three pivots go wrong and the fallback takes over.
+  #
+  # @api private
+  module IntroSort
+    # Ranges this short are finished with insertion sort.
+    SMALL_RANGE = 16
+
+    module_function
+
+    def call(array, compare)
+      sort_range(array, compare, 0, array.length - 1, 2 * Math.log2([array.length, 1].max).floor)
+      array
+    end
+
+    # Sorts +array[low..high]+, falling back to heap sort once +depth_limit+ partitions have been made.
+    def sort_range(array, compare, low, high, depth_limit)
+      while high - low + 1 > SMALL_RANGE
+        return HeapSort.sort_range(array, compare, low, high) if depth_limit.zero?
+
+        depth_limit -= 1
+        split = partition(array, compare, low, high)
+        # Recurse into the smaller side and loop on the larger one, keeping the stack shallow.
+        if split - low < high - split
+          sort_range(array, compare, low, split, depth_limit)
+          low = split + 1
+        else
+          sort_range(array, compare, split + 1, high, depth_limit)
+          high = split
+        end
+      end
+      InsertionSort.sort_range(array, compare, low, high)
+    end
+
+    # Hoare partition around the median of the first, middle and last elements: rearranges +array[low..high]+ so that
+    # no element of +array[low..split]+ is greater than the pivot and no element of +array[split + 1..high]+ is
+    # smaller, and returns +split+.
+    #
+    # Unlike a three-way partition, this barely disturbs input that is already partly ordered, which keeps pivots good
+    # on sorted, reversed and similar inputs. The bounds checks only matter for inconsistent comparisons, where they
+    # keep both sides non-empty so that sorting still finishes.
+    def partition(array, compare, low, high)
+      pivot = array[median_of_three(array, compare, low, (low + high) / 2, high)]
+      i = low - 1
+      j = high + 1
+      loop do
+        i += 1
+        i += 1 while i < high && compare.call(array[i], pivot).negative?
+        j -= 1
+        j -= 1 while j > low && compare.call(array[j], pivot).positive?
+        return j.clamp(low, high - 1) if i >= j
+
+        array[i], array[j] = array[j], array[i]
+      end
+    end
+
+    # Returns whichever of the indices +a+, +b+ and +c+ holds the median of the three elements.
+    def median_of_three(array, compare, a, b, c)
+      if compare.call(array[a], array[b]).negative?
+        return b if compare.call(array[b], array[c]).negative?
+
+        compare.call(array[a], array[c]).negative? ? c : a
+      else
+        return a if compare.call(array[a], array[c]).negative?
+
+        compare.call(array[b], array[c]).negative? ? c : b
+      end
+    end
+  end
+
+  register :intro, IntroSort, title: 'Introsort', stable: false,
+                              best: 'n log n', average: 'n log n', worst: 'n log n', space: 'log n'
+end

data/lib/array_sort/algorithms/merge_sort.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Merge sort: sorts each half, then merges the two sorted halves.
+  #
+  # Top-down: sort each half recursively, then merge them. Merging copies the left half into a scratch buffer that
+  # is allocated once for the whole sort and writes the merged run back into the array. If the two halves are already
+  # in order the merge is skipped, so sorted input costs only O(n) comparisons.
+  #
+  # @api private
+  module MergeSort
+    module_function
+
+    def call(array, compare)
+      sort_range(array, compare, 0, array.length, Array.new(array.length))
+      array
+    end
+
+    # Sorts +array[low...high]+.
+    def sort_range(array, compare, low, high, buffer)
+      return if high - low < 2
+
+      mid = (low + high) / 2
+      sort_range(array, compare, low, mid, buffer)
+      sort_range(array, compare, mid, high, buffer)
+      merge(array, compare, low, mid, high, buffer) if compare.call(array[mid - 1], array[mid]).positive?
+    end
+
+    # Merges the sorted runs +array[low...mid]+ and +array[mid...high]+. On ties the left element wins, which is what
+    # makes the sort stable.
+    def merge(array, compare, low, mid, high, buffer)
+      (low...mid).each { |i| buffer[i] = array[i] }
+      left = low
+      right = mid
+      out = low
+      while left < mid && right < high
+        if compare.call(buffer[left], array[right]).positive?
+          array[out] = array[right]
+          right += 1
+        else
+          array[out] = buffer[left]
+          left += 1
+        end
+        out += 1
+      end
+      # Anything left over on the right is already in place; only leftovers from the left need copying back.
+      while left < mid
+        array[out] = buffer[left]
+        left += 1
+        out += 1
+      end
+    end
+  end
+
+  register :merge, MergeSort, title: 'Merge sort', stable: true,
+                              best: 'n', average: 'n log n', worst: 'n log n', space: 'n'
+end

data/lib/array_sort/algorithms/odd_even_sort.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Odd-even sort (brick sort): alternates between comparing every odd/even pair of neighbours and every even/odd
+  # pair, swapping those that are out of order.
+  #
+  # All the comparisons within a phase are independent, which is why this sort is used on parallel hardware. n rounds
+  # are always enough, so the loop stops there even if the comparison is inconsistent.
+  #
+  # @api private
+  module OddEvenSort
+    module_function
+
+    def call(array, compare)
+      length = array.length
+      length.times do
+        sorted = true
+        [1, 0].each do |start|
+          start.step(length - 2, 2) do |i|
+            next unless compare.call(array[i], array[i + 1]).positive?
+
+            array[i], array[i + 1] = array[i + 1], array[i]
+            sorted = false
+          end
+        end
+        break if sorted
+      end
+      array
+    end
+  end
+
+  register :odd_even, OddEvenSort, title: 'Odd-even sort', stable: true,
+                                   best: 'n', average: 'n²', worst: 'n²', space: '1'
+end

data/lib/array_sort/algorithms/pancake_sort.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Pancake sort: sorts using only "flips", which reverse a prefix of the array, like a spatula flipping the top of a
+  # stack of pancakes.
+  #
+  # For each position from the end, flip the largest remaining element to the front, then flip it down into place.
+  # That takes at most 2n flips.
+  #
+  # @api private
+  module PancakeSort
+    module_function
+
+    def call(array, compare)
+      (array.length - 1).downto(1) do |last|
+        largest = 0
+        (1..last).each { |i| largest = i if compare.call(array[i], array[largest]).positive? }
+        next if largest == last
+
+        flip(array, largest) unless largest.zero?
+        flip(array, last)
+      end
+      array
+    end
+
+    # Reverses +array[0..last]+.
+    def flip(array, last)
+      first = 0
+      while first < last
+        array[first], array[last] = array[last], array[first]
+        first += 1
+        last -= 1
+      end
+    end
+  end
+
+  register :pancake, PancakeSort, title: 'Pancake sort', stable: false,
+                                  best: 'n²', average: 'n²', worst: 'n²', space: '1'
+end

data/lib/array_sort/algorithms/quick_sort.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Quicksort: picks a pivot, partitions the array around it, and sorts each side.
+  #
+  # In place, with a randomly chosen pivot so that no particular input (sorted, reversed, organ-pipe...) reliably
+  # triggers the quadratic worst case, and a three-way (Dutch national flag) partition so that runs of equal elements
+  # are handled in a single pass. Only the smaller partition is sorted recursively and the larger one is handled by the
+  # loop, which keeps the recursion depth at O(log n) no matter how unlucky the pivots are.
+  #
+  # @api private
+  module QuickSort
+    module_function
+
+    def call(array, compare)
+      sort_range(array, compare, 0, array.length - 1)
+      array
+    end
+
+    # Sorts +array[low..high]+.
+    def sort_range(array, compare, low, high)
+      while low < high
+        less_end, greater_start = partition(array, compare, low, high, rand(low..high))
+        if less_end - low < high - greater_start
+          sort_range(array, compare, low, less_end)
+          low = greater_start
+        else
+          sort_range(array, compare, greater_start, high)
+          high = less_end
+        end
+      end
+    end
+
+    # Rearranges +array[low..high]+ into elements less than, equal to, and greater than the pivot +array[pivot_index]+.
+    # Returns the index of the last "less than" element and the first "greater than" element.
+    #
+    # The pivot itself always ends up in the "equal" region, so every call makes progress even if the comparison is
+    # inconsistent (for example, a block that always returns 1).
+    def partition(array, compare, low, high, pivot_index)
+      array[low], array[pivot_index] = array[pivot_index], array[low]
+      pivot = array[low]
+
+      less = low + 1
+      greater = high
+      i = low + 1
+      while i <= greater
+        comparison = compare.call(array[i], pivot)
+        if comparison.negative?
+          array[less], array[i] = array[i], array[less]
+          less += 1
+          i += 1
+        elsif comparison.positive?
+          array[i], array[greater] = array[greater], array[i]
+          greater -= 1
+        else
+          i += 1
+        end
+      end
+
+      # Move the pivot from the front to the end of the "less than" region, i.e. the start of the "equal" region.
+      array[low], array[less - 1] = array[less - 1], array[low]
+      [less - 2, greater + 1]
+    end
+  end
+
+  register :quick, QuickSort, title: 'Quicksort', stable: false,
+                              best: 'n log n', average: 'n log n', worst: 'n²', space: 'log n'
+end

data/lib/array_sort/algorithms/radix_sort.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Radix sort (least significant digit first): sorts Integer keys one byte at a time, starting with the lowest byte,
+  # using a stable counting pass for each. It never compares elements.
+  #
+  # Takes one pass per byte of the widest key, i.e. O(n·w) time where w is the number of bytes needed for the range
+  # of the keys. Negative keys work because every key is measured from the smallest one.
+  #
+  # @api private
+  module RadixSort
+    DIGIT_BITS = 8
+    BASE = 1 << DIGIT_BITS
+    DIGIT_MASK = BASE - 1
+
+    module_function
+
+    def call(array, key)
+      keys = Core.integer_keys(array, key, 'radix sort')
+      return array if keys.length < 2
+
+      min = keys.min
+      keys.map! { |k| k - min } # now every key is >= 0
+      max = keys.max
+      shift = 0
+      while (max >> shift).positive?
+        keys = counting_pass(array, keys, shift)
+        shift += DIGIT_BITS
+      end
+      array
+    end
+
+    # Stably reorders +array+ (and returns +keys+ in the new order) by the digit of each key at bit offset +shift+.
+    def counting_pass(array, keys, shift)
+      starts = Array.new(BASE, 0)
+      keys.each { |k| starts[(k >> shift) & DIGIT_MASK] += 1 }
+      total = 0
+      starts.each_index do |digit|
+        count = starts[digit]
+        starts[digit] = total
+        total += count
+      end
+
+      elements = Array.new(array)
+      reordered_keys = Array.new(keys.length)
+      keys.each_with_index do |k, i|
+        digit = (k >> shift) & DIGIT_MASK
+        array[starts[digit]] = elements[i]
+        reordered_keys[starts[digit]] = k
+        starts[digit] += 1
+      end
+      reordered_keys
+    end
+  end
+
+  register :radix, RadixSort, title: 'Radix sort (LSD)', stable: true, kind: :distribution,
+                              best: 'n·w', average: 'n·w', worst: 'n·w', space: 'n'
+end

data/lib/array_sort/algorithms/selection_sort.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Selection sort: repeatedly finds the smallest remaining element and swaps it to the front.
+  #
+  # Always makes n(n-1)/2 comparisons, but at most n-1 swaps, so it is a reasonable choice when writes are expensive.
+  #
+  # @api private
+  module SelectionSort
+    module_function
+
+    def call(array, compare)
+      length = array.length
+      (0...(length - 1)).each do |i|
+        smallest = i
+        ((i + 1)...length).each { |j| smallest = j if compare.call(array[j], array[smallest]).negative? }
+        array[i], array[smallest] = array[smallest], array[i] unless smallest == i
+      end
+      array
+    end
+  end
+
+  register :selection, SelectionSort, title: 'Selection sort', stable: false,
+                                      best: 'n²', average: 'n²', worst: 'n²', space: '1'
+end

data/lib/array_sort/algorithms/shell_sort.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Shell sort: insertion sort over elements a gap apart, for a shrinking sequence of gaps ending in 1.
+  #
+  # Uses Marcin Ciura's gap sequence (1, 4, 10, 23, 57, 132, 301, 701), extended by a factor of 2.25 for longer
+  # arrays. Its exact complexity is an open problem; in practice it grows a little faster than n log n.
+  #
+  # @api private
+  module ShellSort
+    CIURA_GAPS = [1, 4, 10, 23, 57, 132, 301, 701].freeze
+
+    module_function
+
+    def call(array, compare)
+      length = array.length
+      gaps(length).each do |gap|
+        (gap...length).each do |i|
+          element = array[i]
+          j = i
+          while j >= gap && compare.call(array[j - gap], element).positive?
+            array[j] = array[j - gap]
+            j -= gap
+          end
+          array[j] = element unless j == i
+        end
+      end
+      array
+    end
+
+    # Returns the gaps to use for an array of +length+ elements, largest first.
+    def gaps(length)
+      gaps = CIURA_GAPS.dup
+      gaps << (gaps.last * 2.25).floor while gaps.last < length
+      gaps.select { |gap| gap < length }.reverse
+    end
+  end
+
+  register :shell, ShellSort, title: 'Shell sort', stable: false,
+                              best: 'n log n', average: '≈ n^1.3', worst: 'unknown', space: '1'
+end

data/lib/array_sort/algorithms/smooth_sort.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Smoothsort: Edsger Dijkstra's heap sort variant that runs in O(n) on already-sorted input while keeping heap sort's
+  # O(n log n) worst case and O(1) extra space.
+  #
+  # Instead of one binary heap, it keeps a row of max-heaps whose sizes are Leonardo numbers (1, 1, 3, 5, 9, 15, ...,
+  # each the sum of the previous two plus one), with their roots in ascending order from left to right. The largest
+  # element is therefore always the rightmost root. Growing the row one element at a time builds it; shrinking it one
+  # element at a time, while repairing the row, leaves the array sorted.
+  #
+  # @api private
+  module SmoothSort
+    module_function
+
+    def call(array, compare)
+      length = array.length
+      return array if length < 2
+
+      sizes = leonardo_numbers(length)
+      orders = [] # the order (index into sizes) of each heap in the row, left to right
+
+      # Build: add each element as the root of a new heap, merging the last two heaps when their orders are
+      # consecutive, then move it to its place among the roots.
+      length.times do |root|
+        if orders.length >= 2 && orders[-2] == orders[-1] + 1
+          orders.pop
+          orders[-1] += 1
+        elsif orders.last == 1
+          orders.push(0)
+        else
+          orders.push(1)
+        end
+        restore_roots(array, compare, sizes, orders, orders.length - 1, root)
+      end
+
+      # Take apart: the last element is the largest, so it is in place. Removing it splits its heap into its two
+      # subheaps, whose roots then need to find their place in the row.
+      (length - 1).downto(1) do |root|
+        order = orders.pop
+        next if order < 2
+
+        left_root = root - 1 - sizes[order - 2]
+        orders.push(order - 1)
+        restore_roots(array, compare, sizes, orders, orders.length - 1, left_root)
+        orders.push(order - 2)
+        restore_roots(array, compare, sizes, orders, orders.length - 1, root - 1)
+      end
+      array
+    end
+
+    # Returns the Leonardo numbers up to the first one that is at least +length+.
+    def leonardo_numbers(length)
+      numbers = [1, 1]
+      numbers << (numbers[-1] + numbers[-2] + 1) while numbers.last < length
+      numbers
+    end
+
+    # Moves the value at +root+ (the root of heap +heap+ in the row) leftwards past larger roots, then sifts it down
+    # into whichever heap it ends up in.
+    def restore_roots(array, compare, sizes, orders, heap, root)
+      while heap.positive?
+        previous_root = root - sizes[orders[heap]]
+        break unless compare.call(array[previous_root], array[root]).positive?
+
+        # The previous root may only move into this heap if it is also larger than this root's children.
+        order = orders[heap]
+        if order >= 2
+          right_child = root - 1
+          left_child = right_child - sizes[order - 2]
+          break unless compare.call(array[previous_root], array[left_child]).positive? &&
+                       compare.call(array[previous_root], array[right_child]).positive?
+        end
+
+        array[previous_root], array[root] = array[root], array[previous_root]
+        root = previous_root
+        heap -= 1
+      end
+      sift_down(array, compare, sizes, root, orders[heap])
+    end
+
+    # Restores the max-heap property of the Leonardo heap of the given +order+ rooted at +root+. Its left subheap has
+    # order - 1 and its right subheap order - 2, with the right subheap's root just before +root+.
+    def sift_down(array, compare, sizes, root, order)
+      while order >= 2
+        right_child = root - 1
+        left_child = right_child - sizes[order - 2]
+        if compare.call(array[left_child], array[right_child]).negative?
+          child = right_child
+          child_order = order - 2
+        else
+          child = left_child
+          child_order = order - 1
+        end
+        break unless compare.call(array[root], array[child]).negative?
+
+        array[root], array[child] = array[child], array[root]
+        root = child
+        order = child_order
+      end
+    end
+  end
+
+  register :smooth, SmoothSort, title: 'Smoothsort', stable: false,
+                                best: 'n', average: 'n log n', worst: 'n log n', space: '1'
+end