array-sort 0.1.1 → 1.0.0

data/lib/array_sort/refinements.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Adds the {ArrayMethods} to Array only in files that opt in, instead of everywhere.
+  #
+  # @example
+  #   require 'array_sort'
+  #   using ArraySort::Refinements
+  #
+  #   [3, 1, 2].merge_sort # => [1, 2, 3]
+  module Refinements
+    refine Array do
+      import_methods ArraySort::ArrayMethods
+    end
+  end
+end

data/lib/array_sort/registry.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # Describes one sorting algorithm: what it is called, whether it is stable, and its complexity.
+  #
+  # Complexities are written without the O(...), e.g. +"n log n"+. In the distribution sorts, +k+ is the range of the
+  # keys (largest minus smallest) and +w+ is the number of bytes in the largest key.
+  #
+  # @!attribute [r] name
+  #   @return [Symbol] the method prefix, e.g. +:merge+ for +merge_sort+
+  # @!attribute [r] title
+  #   @return [String] the human-readable name, e.g. +"Merge sort"+
+  # @!attribute [r] kind
+  #   @return [Symbol] +:comparison+ for sorts that compare elements (and accept a comparison block), or
+  #     +:distribution+ for sorts that place elements by numeric key (Integer, or any real number for bucket sort)
+  # @!attribute [r] best
+  #   @return [String] best-case time complexity
+  # @!attribute [r] average
+  #   @return [String] average-case time complexity
+  # @!attribute [r] worst
+  #   @return [String] worst-case time complexity
+  # @!attribute [r] space
+  #   @return [String] extra space used, beyond the copy made by the non-bang methods
+  Algorithm = Data.define(:name, :title, :implementation, :stable, :kind, :best, :average, :worst, :space) do
+    # @return [Boolean] whether elements that compare equal keep their original relative order
+    def stable? = stable
+
+    # @return [Boolean] whether the algorithm sorts by comparing elements
+    def comparison? = kind == :comparison
+
+    # @return [Boolean] whether the algorithm sorts by distributing numeric keys, without comparing elements
+    def distribution? = kind == :distribution
+  end
+
+  @algorithms = {}
+
+  class << self
+    # Returns the names of every available algorithm, in alphabetical order. Each name +x+ provides +x_sort+,
+    # +x_sort!+, +x_sort_by+ and +x_sort_by!+.
+    #
+    # @example
+    #   ArraySort.algorithms # => [:binary_insertion, :bubble, :bucket, ...]
+    # @return [Array<Symbol>]
+    def algorithms
+      @algorithms.keys.sort
+    end
+
+    # Returns the description of an algorithm.
+    #
+    # @example
+    #   ArraySort.algorithm(:merge).stable? # => true
+    # @param name [Symbol, String]
+    # @return [Algorithm]
+    # @raise [ArgumentError] if there is no algorithm with that name
+    def algorithm(name)
+      @algorithms.fetch(name.to_sym) { raise ArgumentError, "unknown sorting algorithm: #{name.inspect}" }
+    end
+
+    private
+
+    # Called by each algorithm file to add itself.
+    def register(name, implementation, title:, stable:, best:, average:, worst:, space:, kind: :comparison)
+      raise "algorithm #{name.inspect} is already registered" if @algorithms.key?(name)
+
+      @algorithms[name] = Algorithm.new(name:, title:, implementation:, stable:, kind:, best:, average:, worst:, space:)
+    end
+  end
+end

data/lib/array_sort/trace.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module ArraySort
+  # A record of everything a sorting algorithm did: every comparison it made and every write to the array, in order.
+  # Build one with {ArraySort.trace}.
+  #
+  # Replaying the writes onto a copy of {#input} reproduces {#result} step by step, which makes traces handy for
+  # visualizing or teaching how the algorithms differ.
+  class Trace
+    # One comparison between two elements. +result+ is -1, 0 or 1.
+    Comparison = Data.define(:left, :right, :result)
+
+    # One assignment +array[index] = value+. A swap shows up as two writes.
+    Write = Data.define(:index, :value)
+
+    # @return [Algorithm] the algorithm that ran
+    attr_reader :algorithm
+    # @return [Array] a copy of the array before sorting
+    attr_reader :input
+    # @return [Array] the sorted array
+    attr_reader :result
+    # @return [Array<Comparison, Write>] everything the algorithm did, in order
+    attr_reader :events
+
+    # @api private
+    def initialize(algorithm, input, result, events)
+      @algorithm = algorithm
+      @input = input
+      @result = result
+      @events = events
+    end
+
+    # @return [Integer] how many comparisons were made
+    def comparisons
+      events.count { |event| event.is_a?(Comparison) }
+    end
+
+    # @return [Integer] how many elements were written
+    def writes
+      events.count { |event| event.is_a?(Write) }
+    end
+
+    # The array handed to the algorithm while tracing. It reports every element assignment.
+    #
+    # @api private
+    class Buffer < Array
+      def initialize(array, on_write)
+        super(array, &nil)
+        @on_write = on_write
+      end
+
+      # Only single-element assignment is supported; algorithms must not use the range or length forms.
+      def []=(index, value)
+        @on_write.call(index, value)
+        super
+      end
+    end
+    private_constant :Buffer
+
+    # @api private
+    def self.run(name, array, &on_event)
+      algorithm = ArraySort.algorithm(name)
+      input = Array.new(array).freeze
+      events = []
+      record = lambda do |event|
+        events << event
+        on_event&.call(event)
+      end
+
+      buffer = Buffer.new(input, ->(index, value) { record.call(Write.new(index:, value:)) })
+      algorithm.implementation.call(buffer, algorithm.comparison? ? recording_comparator(record) : lambda { |element|
+        element
+      })
+      new(algorithm, input, Array.new(buffer), events.freeze)
+    end
+
+    # Compares with <=> like an untraced sort, and records each comparison.
+    def self.recording_comparator(record)
+      compare = Core.comparator(nil)
+      lambda do |a, b|
+        compare.call(a, b).tap { |result| record.call(Comparison.new(left: a, right: b, result: result <=> 0)) }
+      end
+    end
+    private_class_method :recording_comparator
+  end
+
+  class << self
+    # Sorts a copy of +array+ with the named algorithm, recording each comparison and write.
+    #
+    # Elements are compared with +<=>+ (distribution sorts never compare; they need Integer elements, or real numbers
+    # for bucket sort).
+    #
+    # @example
+    #   trace = ArraySort.trace(:insertion, [3, 1, 2])
+    #   trace.result      # => [1, 2, 3]
+    #   trace.comparisons # => 3
+    #   trace.events.first
+    #   # => #<data ArraySort::Trace::Comparison left=3, right=1, result=1>
+    #
+    # @example Streaming events as they happen
+    #   ArraySort.trace(:heap, [3, 1, 2]) { |event| puts event.inspect }
+    #
+    # @param name [Symbol, String] one of {ArraySort.algorithms}
+    # @param array [Array] the array to sort; it is not modified
+    # @yieldparam event [Trace::Comparison, Trace::Write] each event, as it happens
+    # @return [Trace]
+    def trace(name, array, &)
+      Trace.run(name, array, &)
+    end
+  end
+end

data/lib/{array/sort → array_sort}/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ArraySort
-  VERSION = '0.1.1'
+  VERSION = '1.0.0'
 end

data/lib/array_sort.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Popular sorting algorithms for Ruby arrays.
+#
+# Requiring +array_sort+ loads everything without changing Array. From there, sort with the module functions
+# (+ArraySort.merge_sort(array)+), or opt in per file with +using ArraySort::Refinements+. Requiring +array/sort+
+# instead also adds the sort methods to every Array.
+module ArraySort
+end
+
+require_relative 'array_sort/version'
+require_relative 'array_sort/registry'
+require_relative 'array_sort/core'
+
+# Algorithms some others build on come first.
+require_relative 'array_sort/algorithms/bubble_sort'
+require_relative 'array_sort/algorithms/heap_sort'
+require_relative 'array_sort/algorithms/insertion_sort'
+require_relative 'array_sort/algorithms/quick_sort'
+
+require_relative 'array_sort/algorithms/binary_insertion_sort'
+require_relative 'array_sort/algorithms/bucket_sort'
+require_relative 'array_sort/algorithms/cocktail_shaker_sort'
+require_relative 'array_sort/algorithms/comb_sort'
+require_relative 'array_sort/algorithms/counting_sort'
+require_relative 'array_sort/algorithms/cycle_sort'
+require_relative 'array_sort/algorithms/gnome_sort'
+require_relative 'array_sort/algorithms/intro_sort'
+require_relative 'array_sort/algorithms/merge_sort'
+require_relative 'array_sort/algorithms/odd_even_sort'
+require_relative 'array_sort/algorithms/pancake_sort'
+require_relative 'array_sort/algorithms/radix_sort'
+require_relative 'array_sort/algorithms/selection_sort'
+require_relative 'array_sort/algorithms/shell_sort'
+require_relative 'array_sort/algorithms/smooth_sort'
+require_relative 'array_sort/algorithms/tim_sort'
+require_relative 'array_sort/algorithms/tournament_sort'
+require_relative 'array_sort/algorithms/tree_sort'
+
+require_relative 'array_sort/array_methods'
+require_relative 'array_sort/functions'
+require_relative 'array_sort/refinements'
+require_relative 'array_sort/trace'

data/sig/array_sort.rbs

@@ -0,0 +1,368 @@
+# Generated by script/generate_sig.rb from the algorithm registry; run `bundle exec rake sig` to update.
+
+module ArraySort
+  VERSION: String
+
+  type real = Integer | Float | Rational
+
+  def self.algorithms: () -> Array[Symbol]
+  def self.algorithm: (Symbol | String name) -> Algorithm
+  def self.trace: (Symbol | String name, Array[untyped] array) ?{ (Trace::event event) -> void } -> Trace
+
+  def self.binary_insertion_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.binary_insertion_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.binary_insertion_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                                   | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.binary_insertion_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                                    | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.bubble_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.bubble_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.bubble_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                         | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.bubble_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                          | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.bucket_sort: [T] (Array[real] array) -> Array[real]
+  def self.bucket_sort!: [T] (Array[real] array) -> Array[real]
+  def self.bucket_sort_by: [T] (Array[T] array) { (T) -> real } -> Array[T]
+                         | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.bucket_sort_by!: [T] (Array[T] array) { (T) -> real } -> Array[T]
+                          | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.cocktail_shaker_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.cocktail_shaker_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.cocktail_shaker_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                                  | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.cocktail_shaker_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                                   | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.comb_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.comb_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.comb_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                       | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.comb_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                        | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.counting_sort: [T] (Array[Integer] array) -> Array[Integer]
+  def self.counting_sort!: [T] (Array[Integer] array) -> Array[Integer]
+  def self.counting_sort_by: [T] (Array[T] array) { (T) -> Integer } -> Array[T]
+                           | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.counting_sort_by!: [T] (Array[T] array) { (T) -> Integer } -> Array[T]
+                            | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.cycle_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.cycle_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.cycle_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                        | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.cycle_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                         | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.gnome_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.gnome_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.gnome_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                        | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.gnome_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                         | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.heap_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.heap_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.heap_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                       | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.heap_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                        | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.insertion_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.insertion_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.insertion_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                            | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.insertion_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                             | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.intro_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.intro_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.intro_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                        | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.intro_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                         | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.merge_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.merge_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.merge_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                        | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.merge_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                         | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.odd_even_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.odd_even_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.odd_even_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                           | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.odd_even_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                            | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.pancake_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.pancake_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.pancake_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                          | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.pancake_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                           | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.quick_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.quick_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.quick_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                        | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.quick_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                         | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.radix_sort: [T] (Array[Integer] array) -> Array[Integer]
+  def self.radix_sort!: [T] (Array[Integer] array) -> Array[Integer]
+  def self.radix_sort_by: [T] (Array[T] array) { (T) -> Integer } -> Array[T]
+                        | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.radix_sort_by!: [T] (Array[T] array) { (T) -> Integer } -> Array[T]
+                         | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.selection_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.selection_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.selection_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                            | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.selection_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                             | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.shell_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.shell_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.shell_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                        | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.shell_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                         | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.smooth_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.smooth_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.smooth_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                         | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.smooth_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                          | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.tim_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.tim_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.tim_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                      | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.tim_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                       | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.tournament_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.tournament_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.tournament_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                             | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.tournament_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                              | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  def self.tree_sort: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.tree_sort!: [T] (Array[T] array) ?{ (T a, T b) -> Numeric? } -> Array[T]
+  def self.tree_sort_by: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                       | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+  def self.tree_sort_by!: [T] (Array[T] array) { (T) -> untyped } -> Array[T]
+                        | [T] (Array[T] array) -> Enumerator[T, Array[T]]
+
+  class Algorithm < Data
+    attr_reader name: Symbol
+    attr_reader title: String
+    attr_reader implementation: untyped
+    attr_reader stable: bool
+    attr_reader kind: :comparison | :distribution
+    attr_reader best: String
+    attr_reader average: String
+    attr_reader worst: String
+    attr_reader space: String
+    def stable?: () -> bool
+    def comparison?: () -> bool
+    def distribution?: () -> bool
+  end
+
+  class Trace
+    type event = Comparison | Write
+
+    class Comparison < Data
+      attr_reader left: untyped
+      attr_reader right: untyped
+      attr_reader result: Integer
+    end
+
+    class Write < Data
+      attr_reader index: Integer
+      attr_reader value: untyped
+    end
+
+    attr_reader algorithm: Algorithm
+    attr_reader input: Array[untyped]
+    attr_reader result: Array[untyped]
+    attr_reader events: Array[event]
+    def comparisons: () -> Integer
+    def writes: () -> Integer
+  end
+
+  module ArrayMethods[Elem]
+    def swap: (Integer index1, Integer index2) -> self
+
+    def binary_insertion_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def binary_insertion_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def binary_insertion_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                                | () -> Enumerator[Elem, Array[Elem]]
+    def binary_insertion_sort_by!: () { (Elem) -> untyped } -> self
+                                 | () -> Enumerator[Elem, self]
+
+    def bubble_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def bubble_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def bubble_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                      | () -> Enumerator[Elem, Array[Elem]]
+    def bubble_sort_by!: () { (Elem) -> untyped } -> self
+                       | () -> Enumerator[Elem, self]
+
+    def bucket_sort: () -> Array[Elem]
+    def bucket_sort!: () -> self
+    def bucket_sort_by: () { (Elem) -> real } -> Array[Elem]
+                      | () -> Enumerator[Elem, Array[Elem]]
+    def bucket_sort_by!: () { (Elem) -> real } -> self
+                       | () -> Enumerator[Elem, self]
+
+    def cocktail_shaker_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def cocktail_shaker_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def cocktail_shaker_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                               | () -> Enumerator[Elem, Array[Elem]]
+    def cocktail_shaker_sort_by!: () { (Elem) -> untyped } -> self
+                                | () -> Enumerator[Elem, self]
+
+    def comb_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def comb_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def comb_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                    | () -> Enumerator[Elem, Array[Elem]]
+    def comb_sort_by!: () { (Elem) -> untyped } -> self
+                     | () -> Enumerator[Elem, self]
+
+    def counting_sort: () -> Array[Elem]
+    def counting_sort!: () -> self
+    def counting_sort_by: () { (Elem) -> Integer } -> Array[Elem]
+                        | () -> Enumerator[Elem, Array[Elem]]
+    def counting_sort_by!: () { (Elem) -> Integer } -> self
+                         | () -> Enumerator[Elem, self]
+
+    def cycle_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def cycle_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def cycle_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                     | () -> Enumerator[Elem, Array[Elem]]
+    def cycle_sort_by!: () { (Elem) -> untyped } -> self
+                      | () -> Enumerator[Elem, self]
+
+    def gnome_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def gnome_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def gnome_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                     | () -> Enumerator[Elem, Array[Elem]]
+    def gnome_sort_by!: () { (Elem) -> untyped } -> self
+                      | () -> Enumerator[Elem, self]
+
+    def heap_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def heap_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def heap_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                    | () -> Enumerator[Elem, Array[Elem]]
+    def heap_sort_by!: () { (Elem) -> untyped } -> self
+                     | () -> Enumerator[Elem, self]
+
+    def insertion_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def insertion_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def insertion_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                         | () -> Enumerator[Elem, Array[Elem]]
+    def insertion_sort_by!: () { (Elem) -> untyped } -> self
+                          | () -> Enumerator[Elem, self]
+
+    def intro_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def intro_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def intro_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                     | () -> Enumerator[Elem, Array[Elem]]
+    def intro_sort_by!: () { (Elem) -> untyped } -> self
+                      | () -> Enumerator[Elem, self]
+
+    def merge_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def merge_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def merge_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                     | () -> Enumerator[Elem, Array[Elem]]
+    def merge_sort_by!: () { (Elem) -> untyped } -> self
+                      | () -> Enumerator[Elem, self]
+
+    def odd_even_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def odd_even_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def odd_even_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                        | () -> Enumerator[Elem, Array[Elem]]
+    def odd_even_sort_by!: () { (Elem) -> untyped } -> self
+                         | () -> Enumerator[Elem, self]
+
+    def pancake_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def pancake_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def pancake_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                       | () -> Enumerator[Elem, Array[Elem]]
+    def pancake_sort_by!: () { (Elem) -> untyped } -> self
+                        | () -> Enumerator[Elem, self]
+
+    def quick_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def quick_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def quick_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                     | () -> Enumerator[Elem, Array[Elem]]
+    def quick_sort_by!: () { (Elem) -> untyped } -> self
+                      | () -> Enumerator[Elem, self]
+
+    def radix_sort: () -> Array[Elem]
+    def radix_sort!: () -> self
+    def radix_sort_by: () { (Elem) -> Integer } -> Array[Elem]
+                     | () -> Enumerator[Elem, Array[Elem]]
+    def radix_sort_by!: () { (Elem) -> Integer } -> self
+                      | () -> Enumerator[Elem, self]
+
+    def selection_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def selection_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def selection_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                         | () -> Enumerator[Elem, Array[Elem]]
+    def selection_sort_by!: () { (Elem) -> untyped } -> self
+                          | () -> Enumerator[Elem, self]
+
+    def shell_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def shell_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def shell_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                     | () -> Enumerator[Elem, Array[Elem]]
+    def shell_sort_by!: () { (Elem) -> untyped } -> self
+                      | () -> Enumerator[Elem, self]
+
+    def smooth_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def smooth_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def smooth_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                      | () -> Enumerator[Elem, Array[Elem]]
+    def smooth_sort_by!: () { (Elem) -> untyped } -> self
+                       | () -> Enumerator[Elem, self]
+
+    def tim_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def tim_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def tim_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                   | () -> Enumerator[Elem, Array[Elem]]
+    def tim_sort_by!: () { (Elem) -> untyped } -> self
+                    | () -> Enumerator[Elem, self]
+
+    def tournament_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def tournament_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def tournament_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                          | () -> Enumerator[Elem, Array[Elem]]
+    def tournament_sort_by!: () { (Elem) -> untyped } -> self
+                           | () -> Enumerator[Elem, self]
+
+    def tree_sort: () ?{ (Elem a, Elem b) -> Numeric? } -> Array[Elem]
+    def tree_sort!: () ?{ (Elem a, Elem b) -> Numeric? } -> self
+    def tree_sort_by: () { (Elem) -> untyped } -> Array[Elem]
+                    | () -> Enumerator[Elem, Array[Elem]]
+    def tree_sort_by!: () { (Elem) -> untyped } -> self
+                     | () -> Enumerator[Elem, self]
+
+  end
+
+  module Refinements
+  end
+end
+
+class Array[unchecked out Elem]
+  include ArraySort::ArrayMethods[Elem]
+end