array-sort 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91c86c745cc5568df53cec34a27f8da0a3b3b24899d0016150b794998b3da1c5
-  data.tar.gz: d63474b2f370ef3454ea7978acb838bf8901e51caf30f668dc9f2392f600befc
+  metadata.gz: b2f62e8f149a2fed7b2f3d2b9e2eb69a1944559122dd4012972fd2f2bc029dd5
+  data.tar.gz: 20498925f9a617fc59913a762e5d7997d09a765dfadfbf7e8583a2ad89c85d98
 SHA512:
-  metadata.gz: af69d008cb08440a894f1ee58583e565dcf4994a5825fd0f57415cbd8aea1fc90bc493c47d73be7e0c5304a8651fa7cd003fbda1a22d97ac3c16e658193ebdc4
-  data.tar.gz: 4dc3acb9501663a583d921c9fef4a50074eace63b1b67ebdc1eead7507e0ffef05c78ed60047fa796c4538e937e8776c71ecd7cd52093815f80d17fb5405af9c
+  metadata.gz: 050e9660a9586a8dff0b7a5bee3e565d5bc1aee445e519cb512e2d9e9c6b476a5f2ffbb171abbd238595cee1f2d3039c2c8ccc1e7e62acc4aade725cd210f9c0
+  data.tar.gz: 36d984fc22fe1fc955ec9bfe74cc951f6b4593f88a8fa6af2a959784fbf493d1f33c67d5d6e8762c11738d138aa4e4787c66e18ab3b2c65fd16ccb07b0a3bde4

data/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-10-10
+
+The five original algorithms keep their public API (`*_sort`, `*_sort!`, `*_sort_by`, `*_sort_by!` and `Array#swap`),
+and `require 'array/sort'` still adds them to every Array. But several behaviors were wrong and have been fixed, and
+the gem grows from 5 algorithms to 22, which is why this is a major release. If you relied on any of the old behavior
+listed under "Changed", please check your code.
+
+### Added
+
+- 17 new algorithms, each with the same four methods as the originals:
+  - Simple sorts: binary insertion, cocktail shaker, comb, cycle, gnome, odd-even, pancake and selection sort.
+  - Efficient comparison sorts: shell sort, smoothsort, tree sort (AVL) and tournament sort.
+  - Hybrid sorts: introsort and Timsort.
+  - Distribution sorts, which sort by Integer (or, for bucket sort, real number) keys without comparing: counting,
+    radix (LSD) and bucket sort.
+- `require 'array_sort'`, which loads the gem without changing Array. From there, use `using ArraySort::Refinements`
+  to add the methods to Array in one file only, or module functions such as `ArraySort.merge_sort(array)`.
+- `ArraySort.trace(:algorithm, array)`, which records every comparison and write an algorithm makes.
+- `ArraySort.algorithms` and `ArraySort.algorithm(name)`, describing each algorithm's stability and complexity.
+- RBS type signatures in `sig/`, generated from the algorithm registry.
+- `rake bench`, which benchmarks every algorithm against `Array#sort`.
+- GitHub Actions CI testing Ruby 3.3, 3.4 and 4.0, and running RuboCop and RBS validation.
+- A Release workflow that publishes to RubyGems.org with trusted publishing, and Dependabot for dependency updates.
+- RubyGems metadata (source, changelog and issue tracker links) and MFA requirement for publishing.
+
+### Fixed
+
+- `merge_sort` and `quick_sort` (and their `!`/`_by` variants) only applied a custom comparison block at the top level
+  of the recursion, so sorting with a block, e.g. in descending order, usually returned a wrongly ordered array.
+- `insertion_sort` and `heap_sort` treated only exactly `1`/`-1` as "greater"/"less", so a block returning other
+  numbers (like `a - b`) produced unsorted output.
+- `quick_sort` raised `SystemStackError` on large sorted arrays (about 10,000 elements) and took quadratic time on
+  sorted or reverse-sorted input.
+- Comparing incomparable elements raised `NoMethodError` instead of `ArgumentError`, as `Array#sort` does.
+- `Array#swap` with an out-of-range index silently grew the array and filled it with `nil`s. It now raises
+  `IndexError`.
+
+### Changed
+
+- Ruby 3.3 or later is required.
+- Bang methods check for a frozen receiver before doing any work, so they raise `FrozenError` even if the array is
+  already sorted, and without calling the block.
+- Bang methods leave the receiver untouched if the comparison raises partway through, like `Array#sort!`.
+- The `_by` methods call their block exactly once per element (previously up to twice per comparison).
+- Non-bang methods always return a plain `Array`, even for subclasses of `Array`, like `Array#sort`.
+- Rewrote merge sort and quicksort to stop allocating new arrays at every level of recursion: merge sort now merges
+  with indices and a single scratch buffer, and quicksort sorts in place with a random pivot and three-way
+  partitioning. Insertion sort shifts elements instead of swapping them.
+- The private helper methods the gem used to add to `Array` (`sort_compare`, `become_clone_of`, `heapify`,
+  `sift_down` and others) were removed. The algorithms now live in the `ArraySort` module and no longer add anything
+  to `Array` beyond the public sort methods and `swap`.
+- The Array methods are now defined in `ArraySort::ArrayMethods`, which `require 'array/sort'` includes into Array,
+  instead of directly on Array. The files under `lib/array/sort/` other than `lib/array/sort.rb` itself are gone, so
+  `require 'array/sort'` is the only way to load the patch.
+- Enumerators returned by the `_by` methods now report their `size`, and work under the refinement too.
+
+### Removed
+
+- Travis CI configuration.
+- `bundler` as a development dependency in the gemspec. Development dependencies now live in the `Gemfile`.
+
+## [0.1.1] - 2018-05-11
+
+- Initial public release with bubble sort, heap sort, insertion sort, merge sort and quicksort.
+
+[1.0.0]: https://github.com/foxhatleo/array-sort/compare/0c3220b...v1.0.0
+[0.1.1]: https://github.com/foxhatleo/array-sort/commit/0c3220b

data/README.md

@@ -1,20 +1,26 @@
 # ArraySort
 
-ArraySort adds methods in the Ruby Array class that provides sorting methods using popular sorting algorithms.
+[![Gem Version](https://badge.fury.io/rb/array-sort.svg)](https://badge.fury.io/rb/array-sort)
+[![CI](https://github.com/foxhatleo/array-sort/actions/workflows/ci.yml/badge.svg)](https://github.com/foxhatleo/array-sort/actions/workflows/ci.yml)
 
-Currently, the following sorting algorithms are implemented:
- * Bubble sort _(stable)_
- * Heap sort _(unstable)_
- * Insertion sort _(stable)_
- * Merge sort _(stable)_
- * Quicksort _(unstable)_
+ArraySort implements 22 sorting algorithms for Ruby arrays, from bubble sort to Timsort, all with the same interface
+as `Array#sort`, `#sort!`, `#sort_by` and `#sort_by!`. Use them as `Array` methods, through a refinement, or as plain
+module functions, and trace any of them to watch every comparison and write it makes.
 
-Note that this gem does not overwrite `Array#sort`, `Array#sort!`, `Array#sort_by`, or `Array#sort_by!`. Calling those
-methods will invoke the native sorting methods, which use in-place quicksort algorithm and are unstable.
+```ruby
+[3, 1, 2].tim_sort                                  # => [1, 2, 3]
+[3, 1, 2].merge_sort { |a, b| b <=> a }             # => [3, 2, 1]
+%w[pear fig apple kiwi].merge_sort_by(&:length)     # => ["fig", "pear", "kiwi", "apple"]
+ArraySort.trace(:insertion, [3, 1, 2]).comparisons  # => 3
+```
+
+This gem does not override `Array#sort` and friends. Ruby's native sort is written in C and is much faster than
+anything here, but it is not stable. Reach for ArraySort when you need a stable sort, want a specific algorithm's
+guarantees, or want to learn and compare how the algorithms behave.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Requires Ruby 3.3 or later. Add this line to your application's Gemfile:
 
 ```ruby
 gem 'array-sort'
@@ -22,47 +28,240 @@ gem 'array-sort'
 
 And then execute:
 
-    $ bundle
+    $ bundle install
 
 Or install it yourself as:
 
     $ gem install array-sort
 
+## Loading it
+
+There are three ways to use ArraySort, depending on whether you want it to change `Array`.
+
+**Patch `Array` everywhere.** This is what Bundler does by default for `gem 'array-sort'`, and what
+`require 'array/sort'` does. Every array gets the sort methods.
+
+```ruby
+require 'array/sort'
+
+[3, 1, 2].heap_sort # => [1, 2, 3]
+```
+
+**Refine `Array` in one file.** Load the gem without patching (in a Gemfile, `gem 'array-sort', require: 'array_sort'`),
+then opt in per file with `using`. Code outside that file never sees the methods.
+
+```ruby
+require 'array_sort'
+using ArraySort::Refinements
+
+[3, 1, 2].heap_sort # => [1, 2, 3]
+```
+
+**Module functions.** Also available after `require 'array_sort'`, without touching `Array` at all. Each takes the
+array as its first argument.
+
+```ruby
+require 'array_sort'
+
+ArraySort.merge_sort([3, 1, 2])                # => [1, 2, 3]
+ArraySort.quick_sort_by(%w[ccc a bb], &:size)  # => ["a", "bb", "ccc"]
+ArraySort.insertion_sort!(array)               # sorts array in place
+```
+
+## Algorithms
+
+Every algorithm `x` comes with `x_sort`, `x_sort!`, `x_sort_by` and `x_sort_by!`. Complexities are in big-O notation.
+In the distribution sorts, k is the range of the keys (largest minus smallest) and w is the number of bytes needed for
+that range.
+
+### Simple sorts
+
+| Algorithm             | Method                  | Best    | Average | Worst | Extra space | Stable |
+| --------------------- | ----------------------- | ------- | ------- | ----- | ----------- | ------ |
+| Bubble sort           | `bubble_sort`           | n       | n²      | n²    | 1           | Yes    |
+| Cocktail shaker sort  | `cocktail_shaker_sort`  | n       | n²      | n²    | 1           | Yes    |
+| Comb sort             | `comb_sort`             | n log n | n²/2ᵖ   | n²    | 1           | No     |
+| Gnome sort            | `gnome_sort`            | n       | n²      | n²    | 1           | Yes    |
+| Odd-even sort         | `odd_even_sort`         | n       | n²      | n²    | 1           | Yes    |
+| Insertion sort        | `insertion_sort`        | n       | n²      | n²    | 1           | Yes    |
+| Binary insertion sort | `binary_insertion_sort` | n log n | n²      | n²    | 1           | Yes    |
+| Selection sort        | `selection_sort`        | n²      | n²      | n²    | 1           | No     |
+| Cycle sort            | `cycle_sort`            | n²      | n²      | n²    | 1           | No     |
+| Pancake sort          | `pancake_sort`          | n²      | n²      | n²    | 1           | No     |
+
+### Efficient comparison sorts
+
+| Algorithm       | Method            | Best    | Average | Worst   | Extra space | Stable |
+| --------------- | ----------------- | ------- | ------- | ------- | ----------- | ------ |
+| Merge sort      | `merge_sort`      | n       | n log n | n log n | n           | Yes    |
+| Quicksort       | `quick_sort`      | n log n | n log n | n²      | log n       | No     |
+| Heap sort       | `heap_sort`       | n log n | n log n | n log n | 1           | No     |
+| Shell sort      | `shell_sort`      | n log n | ≈ n^1.3 | unknown | 1           | No     |
+| Smoothsort      | `smooth_sort`     | n       | n log n | n log n | 1           | No     |
+| Tree sort (AVL) | `tree_sort`       | n log n | n log n | n log n | n           | Yes    |
+| Tournament sort | `tournament_sort` | n log n | n log n | n log n | n           | Yes    |
+
+### Hybrid sorts
+
+| Algorithm | Method       | Best    | Average | Worst   | Extra space | Stable |
+| --------- | ------------ | ------- | ------- | ------- | ----------- | ------ |
+| Introsort | `intro_sort` | n log n | n log n | n log n | log n       | No     |
+| Timsort   | `tim_sort`   | n       | n log n | n log n | n           | Yes    |
+
+### Distribution sorts
+
+| Algorithm        | Method          | Best  | Average | Worst | Extra space | Stable |
+| ---------------- | --------------- | ----- | ------- | ----- | ----------- | ------ |
+| Counting sort    | `counting_sort` | n + k | n + k   | n + k | n + k       | Yes    |
+| Radix sort (LSD) | `radix_sort`    | n·w   | n·w     | n·w   | n           | Yes    |
+| Bucket sort      | `bucket_sort`   | n     | n       | n²    | n           | Yes    |
+
+A few notes worth knowing:
+
+ * **Quicksort** picks a random pivot, so its O(n²) worst case is vanishingly unlikely on any input, sorted and
+   reversed arrays included.
+ * **Introsort** (C++'s `std::sort`) is quicksort that falls back to heap sort when partitioning goes badly, and uses
+   insertion sort for short ranges, so its worst case is O(n log n).
+ * **Timsort** (Python's `sorted`, Java's object sort) finds runs that are already in order and merges them, so sorted,
+   reversed and partly sorted data sort in close to linear time.
+ * **Smoothsort** is a heap sort that takes linear time on sorted input, without extra memory.
+ * **Comb sort's** average case depends on the number of passes p; in practice it is close to n log n. Shell sort's
+   complexity with the gap sequence used here (Ciura's) is an open problem.
+ * **Cycle sort** writes each element at most once, the minimum possible, at the cost of many comparisons.
+ * **Gnome sort** uses the common variant where the gnome remembers where it left off.
+
+You can also ask the gem about its algorithms:
+
+```ruby
+ArraySort.algorithms                # => [:binary_insertion, :bubble, :bucket, :cocktail_shaker, ...]
+ArraySort.algorithm(:tim).stable?   # => true
+ArraySort.algorithm(:tim).worst     # => "n log n"
+```
+
 ## Usage
 
-All sort methods share the same signature of `Array#sort`, `Array#sort!`, `Array#sort_by` and `Array#sort_by!`. Simply
-change the names of the sorting methods to the following corresponding methods of a specific sorting algorithm:
+The methods behave like their native counterparts (see the
+[Ruby documentation](https://docs.ruby-lang.org/en/master/Array.html#method-i-sort)):
+
+```ruby
+[3, 1, 2].insertion_sort                                   # => [1, 2, 3]
+[3, 1, 2].merge_sort { |a, b| b <=> a }                    # => [3, 2, 1]
+[[3, 3], [1, 4], [2, 6]].insertion_sort_by { |e| e[0] }    # => [[1, 4], [2, 6], [3, 3]]
+
+array = [3, 1, 2]
+array.smooth_sort!                                         # => [1, 2, 3], and array is now sorted
+```
+
+ * Without a bang, a new `Array` is returned and the receiver is left alone.
+ * With a bang, the receiver is sorted in place and returned. If the comparison raises partway through, the receiver
+   is left unchanged. Calling a bang method on a frozen array raises `FrozenError`.
+ * A comparison block may return any number; only its sign matters. If two elements can't be compared (`<=>` or the
+   block returns `nil`), an `ArgumentError` is raised.
+ * The `_by` methods call their block exactly once per element, and return an `Enumerator` when called without one.
+
+### Distribution sorts
+
+Counting, radix and bucket sort never compare elements. Instead they place each element by a numeric key, which is
+the element itself for `x_sort`, or whatever the block returns for `x_sort_by`. Counting and radix sort need Integer
+keys (negative and arbitrarily large ones are fine); bucket sort takes any finite real number. Because they don't
+compare, `x_sort` and `x_sort!` raise `ArgumentError` when given a comparison block.
+
+```ruby
+[10, -3, 2**70, 0].radix_sort        # => [-3, 0, 10, 1180591620717411303424]
+[0.42, 0.07, 0.99, 0.5].bucket_sort  # => [0.07, 0.42, 0.5, 0.99]
+
+people.radix_sort_by { |person| person[:age] } # stable, so people of the same age keep their order
+```
+
+Counting sort allocates a table as large as the range of the keys, so it raises `RangeError` for ranges above
+max(2²⁰, 4n) rather than running out of memory. Radix sort is the better choice there.
+
+### `Array#swap`
 
- * Bubble sort: `bubble_sort`, `bubble_sort!`, `bubble_sort_by`, `bubble_sort_by!`
- * Heap sort: `heap_sort`, `heap_sort!`, `heap_sort_by`, `heap_sort_by!`
- * Insertion sort: `insertion_sort`, `insertion_sort!`, `insertion_sort_by`, `insertion_sort_by!`
- * Merge sort: `merge_sort`, `merge_sort!`, `merge_sort_by`, `merge_sort_by!`
- * Quicksort: `quick_sort`, `quick_sort!`, `quick_sort_by`, `quick_sort_by!`
- 
-See the official [Ruby documentation](https://ruby-doc.org/core-2.5.0/Array.html#method-i-sort) on how to use the native
-sorting methods of Array.
+The gem also adds `swap`, which swaps two elements in place and returns the array:
 
-For example, to sort an array using insertion sort:
+```ruby
+[1, 2, 3].swap(0, -1) # => [3, 2, 1]
+```
+
+## Tracing
+
+`ArraySort.trace` sorts a copy of an array and records every comparison and every write the algorithm makes, which is
+handy for visualizing algorithms or seeing how they differ.
 
 ```ruby
-[3, 1, 2].insertion_sort # => [1, 2, 3]
+trace = ArraySort.trace(:insertion, [3, 1, 2])
+trace.result       # => [1, 2, 3]
+trace.comparisons  # => 3
+trace.writes       # => 4
+trace.events
+# => [#<data ArraySort::Trace::Comparison left=3, right=1, result=1>,
+#     #<data ArraySort::Trace::Write index=1, value=3>,
+#     #<data ArraySort::Trace::Write index=0, value=1>,
+#     #<data ArraySort::Trace::Comparison left=3, right=2, result=1>,
+#     #<data ArraySort::Trace::Write index=2, value=3>,
+#     #<data ArraySort::Trace::Comparison left=1, right=2, result=-1>,
+#     #<data ArraySort::Trace::Write index=1, value=2>]
 
-# The following two lines both produce [[1, 4], [2, 6], [3, 3]]
-[[3, 3], [1, 4], [2, 6]].insertion_sort { |a, b| a[0] <=> b[0] }
-[[3, 3], [1, 4], [2, 6]].insertion_sort_by { |e| e[0] }
+# Stream events as they happen
+ArraySort.trace(:heap, [5, 1, 4, 2, 3]) { |event| puts event.inspect }
 ```
 
+Replaying the writes onto a copy of `trace.input` reproduces the sort step by step. A swap shows up as two writes.
+For example, sorting `[5, 1, 4, 2, 3]`:
+
+| Algorithm | Comparisons | Writes |
+| --------- | ----------- | ------ |
+| Bubble    | 9           | 12     |
+| Insertion | 9           | 10     |
+| Selection | 10          | 8      |
+| Cycle     | 31          | 5      |
+| Merge     | 11          | 10     |
+| Heap      | 9           | 16     |
+
+Elements are compared with `<=>`. Distribution sorts make no comparisons at all.
+
+## Benchmarks
+
+`bundle exec rake bench` compares every algorithm with `Array#sort`. `SIZE`, `SHAPE` (`random`, `sorted`,
+`reversed` or `few`) and `ALGORITHMS` (comma-separated names) are optional. For example:
+
+    $ SIZE=10000 SHAPE=sorted ALGORITHMS=merge,tim,smooth bundle exec rake bench
+
+## Type signatures
+
+RBS signatures for the whole public API ship with the gem in `sig/array_sort.rbs`. They are generated from the
+algorithm registry with `bundle exec rake sig`.
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can
-also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies, then `bundle exec rake` to run the tests,
+RuboCop and the RBS validation. You can also run `bin/console` for an interactive prompt that will allow you to
+experiment.
+
+Each algorithm lives in its own file in `lib/array_sort/algorithms/` and registers itself with its name, stability
+and complexity. Registering it is all it takes for it to get its four `Array` methods, module functions, refinement,
+tracing, benchmark and type signatures, and to run against the full shared test suite. To add one:
+
+1. Add `lib/array_sort/algorithms/x_sort.rb` and require it from `lib/array_sort.rb`. A comparison sort implements
+   `call(array, compare)`, a distribution sort `call(array, key)`; both sort `array` in place and may only change it
+   with single-element assignment (`array[i] = value`), which is what makes tracing work.
+2. Add its row to the tables above (a test checks that they match the registry).
+3. Run `bundle exec rake sig` to regenerate the type signatures.
+
+### Releasing
+
+Releases are published from GitHub Actions with RubyGems trusted publishing, so no API key is needed. Once, on
+rubygems.org, add a trusted publisher for this gem (repository `foxhatleo/array-sort`, workflow `release.yml`,
+environment `release`). Then, for each release, bump `ArraySort::VERSION` and the CHANGELOG, merge to `master`, and
+run the **Release** workflow from the Actions tab. It runs the tests, pushes the gem and tags the release.
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at
 [https://github.com/foxhatleo/array-sort](https://github.com/foxhatleo/array-sort). This project is intended to be a
 safe, welcoming space for collaboration, and contributors are expected to adhere to the
-[Contributor Covenant](http://contributor-covenant.org) code of conduct.
+[Contributor Covenant](https://www.contributor-covenant.org) code of conduct.
 
 ## License
 

data/lib/array/sort.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
-#
-require 'array/sort/version'
-require 'array/sort/helper'
-require 'array/sort/merge_sort'
-require 'array/sort/insertion_sort'
-require 'array/sort/heap_sort'
-require 'array/sort/bubble_sort'
-require 'array/sort/quick_sort'
+# Loads ArraySort and adds its sort methods to every Array. Use +require 'array_sort'+ instead to load it without
+# changing Array.
+require_relative '../array_sort'
+
+Array.include(ArraySort::ArrayMethods)

data/lib/array_sort/algorithms/binary_insertion_sort.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Binary insertion sort: insertion sort that finds each element's position with a binary search.
+  #
+  # Needs only O(n log n) comparisons, which helps when comparing is expensive, but still moves O(n²) elements. The
+  # search finds the position after any equal elements, which keeps the sort stable.
+  #
+  # @api private
+  module BinaryInsertionSort
+    module_function
+
+    def call(array, compare)
+      (1...array.length).each do |i|
+        element = array[i]
+        position = upper_bound(array, compare, element, 0, i)
+        next if position == i
+
+        i.downto(position + 1) { |j| array[j] = array[j - 1] }
+        array[position] = element
+      end
+      array
+    end
+
+    # Returns the first index in +array[low...high]+ whose element is greater than +element+.
+    def upper_bound(array, compare, element, low, high)
+      while low < high
+        mid = (low + high) / 2
+        if compare.call(element, array[mid]).negative?
+          high = mid
+        else
+          low = mid + 1
+        end
+      end
+      low
+    end
+  end
+
+  register :binary_insertion, BinaryInsertionSort, title: 'Binary insertion sort', stable: true,
+                                                   best: 'n log n', average: 'n²', worst: 'n²', space: '1'
+end

data/lib/array_sort/algorithms/bubble_sort.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Bubble sort: repeatedly walks the array swapping adjacent elements that are out of order.
+  #
+  # Each pass remembers where its last swap happened; everything after that point is already in place, so the next
+  # pass stops there. An already-sorted array therefore takes a single pass.
+  #
+  # @api private
+  module BubbleSort
+    module_function
+
+    def call(array, compare)
+      unsorted_length = array.length
+      while unsorted_length > 1
+        last_swap = 0
+        (1...unsorted_length).each do |i|
+          next unless compare.call(array[i - 1], array[i]).positive?
+
+          array[i - 1], array[i] = array[i], array[i - 1]
+          last_swap = i
+        end
+        unsorted_length = last_swap
+      end
+      array
+    end
+  end
+
+  register :bubble, BubbleSort, title: 'Bubble sort', stable: true,
+                                best: 'n', average: 'n²', worst: 'n²', space: '1'
+end

data/lib/array_sort/algorithms/bucket_sort.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Bucket sort: spreads the elements over n buckets by where their key falls between the smallest and largest key,
+  # sorts each bucket with insertion sort, then concatenates the buckets.
+  #
+  # Keys can be any finite real numbers (Integer, Float, Rational, BigDecimal...). When they are spread evenly most
+  # buckets hold one or two elements and the sort takes O(n); when they cluster, a bucket can fill up and insertion
+  # sort makes it O(n²).
+  #
+  # @api private
+  module BucketSort
+    module_function
+
+    def call(array, key)
+      keys = Core.real_keys(array, key, 'bucket sort')
+      count = keys.length
+      return array if count < 2
+
+      min, max = keys.minmax
+      return array if min == max
+
+      buckets = Array.new(count) { [] }
+      keys.each_with_index do |k, i|
+        index = (fraction(k, min, max) * (count - 1)).floor.clamp(0, count - 1)
+        buckets[index] << i
+      end
+
+      elements = Array.new(array)
+      position = 0
+      buckets.each do |bucket|
+        insertion_sort_by_key(bucket, keys)
+        bucket.each do |i|
+          array[position] = elements[i]
+          position += 1
+        end
+      end
+      array
+    end
+
+    # Where +k+ falls between +min+ (0.0) and +max+ (1.0). Every step only ever rounds in the same direction for larger
+    # keys, so a larger key never lands in an earlier bucket.
+    def fraction(k, min, max)
+      span = max - min
+      return (k - min).fdiv(span) if span.finite?
+
+      # Only floats near Float::MAX get here: halving everything first keeps the arithmetic from overflowing.
+      ((k / 2) - (min / 2)) / ((max / 2) - (min / 2))
+    end
+
+    # Sorts a bucket (a list of element indices) by key. Only strictly larger keys move, so the sort is stable.
+    def insertion_sort_by_key(bucket, keys)
+      (1...bucket.length).each do |i|
+        index = bucket[i]
+        j = i
+        while j.positive? && keys[bucket[j - 1]] > keys[index]
+          bucket[j] = bucket[j - 1]
+          j -= 1
+        end
+        bucket[j] = index
+      end
+    end
+  end
+
+  register :bucket, BucketSort, title: 'Bucket sort', stable: true, kind: :distribution,
+                                best: 'n', average: 'n', worst: 'n²', space: 'n'
+end

data/lib/array_sort/algorithms/cocktail_shaker_sort.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Cocktail shaker sort: bubble sort that alternates direction, carrying the largest element to the end on the way
+  # up and the smallest to the front on the way down.
+  #
+  # Moving in both directions fixes bubble sort's "turtles" (small elements near the end, which bubble sort moves only
+  # one step per pass). Each pass also narrows the unsorted range to where its last swap happened.
+  #
+  # @api private
+  module CocktailShakerSort
+    module_function
+
+    def call(array, compare)
+      low = 0
+      high = array.length - 1
+      while low < high
+        last_swap = low
+        (low...high).each do |i|
+          next unless compare.call(array[i], array[i + 1]).positive?
+
+          array[i], array[i + 1] = array[i + 1], array[i]
+          last_swap = i
+        end
+        high = last_swap
+
+        last_swap = high
+        (high - 1).downto(low) do |i|
+          next unless compare.call(array[i], array[i + 1]).positive?
+
+          array[i], array[i + 1] = array[i + 1], array[i]
+          last_swap = i + 1
+        end
+        low = last_swap
+      end
+      array
+    end
+  end
+
+  register :cocktail_shaker, CocktailShakerSort, title: 'Cocktail shaker sort', stable: true,
+                                                 best: 'n', average: 'n²', worst: 'n²', space: '1'
+end

data/lib/array_sort/algorithms/comb_sort.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Comb sort: bubble sort that first compares elements far apart, shrinking the gap by a factor of 1.3 each pass.
+  #
+  # The long-range passes move small elements near the end ("turtles") forward quickly; once the gap reaches 1, a
+  # final bubble sort finishes the job on an array that is already nearly sorted.
+  #
+  # @api private
+  module CombSort
+    SHRINK_FACTOR = 1.3
+
+    module_function
+
+    def call(array, compare)
+      gap = array.length
+      loop do
+        gap = (gap / SHRINK_FACTOR).floor
+        break if gap <= 1
+
+        (0...(array.length - gap)).each do |i|
+          next unless compare.call(array[i], array[i + gap]).positive?
+
+          array[i], array[i + gap] = array[i + gap], array[i]
+        end
+      end
+      BubbleSort.call(array, compare)
+    end
+  end
+
+  register :comb, CombSort, title: 'Comb sort', stable: false,
+                            best: 'n log n', average: 'n²/2ᵖ', worst: 'n²', space: '1'
+end

data/lib/array_sort/algorithms/counting_sort.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Counting sort: counts how many times each Integer key occurs, works out from the counts where each key's elements
+  # start, then places every element directly. It never compares elements.
+  #
+  # Takes O(n + k) time and space, where k is the range of the keys (largest minus smallest), so it is only practical
+  # when that range is small. Ranges above max(2^20, 4n) raise RangeError rather than allocating a huge table; radix
+  # sort handles wide ranges.
+  #
+  # @api private
+  module CountingSort
+    MAX_RANGE = 1 << 20
+
+    module_function
+
+    def call(array, key)
+      keys = Core.integer_keys(array, key, 'counting sort')
+      return array if keys.length < 2
+
+      min, max = keys.minmax
+      range = max - min + 1
+      limit = [MAX_RANGE, keys.length * 4].max
+      if range > limit
+        raise RangeError, "counting sort can't handle a key range of #{range} (limit #{limit}); try radix_sort instead"
+      end
+
+      # starts[k] is where the next element with key (min + k) goes.
+      starts = Array.new(range, 0)
+      keys.each { |k| starts[k - min] += 1 }
+      total = 0
+      starts.each_index do |i|
+        count = starts[i]
+        starts[i] = total
+        total += count
+      end
+
+      elements = Array.new(array)
+      elements.each_with_index do |element, i|
+        slot = keys[i] - min
+        array[starts[slot]] = element
+        starts[slot] += 1
+      end
+      array
+    end
+  end
+
+  register :counting, CountingSort, title: 'Counting sort', stable: true, kind: :distribution,
+                                    best: 'n + k', average: 'n + k', worst: 'n + k', space: 'n + k'
+end