array-sort 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19712ae85993b11b3c6aa80b1b12557b3fe44081c736588fdb95491c888f9465
-  data.tar.gz: 52adc3ab55c79a36af340b7ba0276a3ea31a759f6e93224dc3496d8c13d34d4e
+  metadata.gz: 91c86c745cc5568df53cec34a27f8da0a3b3b24899d0016150b794998b3da1c5
+  data.tar.gz: d63474b2f370ef3454ea7978acb838bf8901e51caf30f668dc9f2392f600befc
 SHA512:
-  metadata.gz: 2f001fcef739c8843ea6b6d66813123d5c51c8c8ba2bc9d7ba633859914270671701087cc93a85ec7a7591582eab0d7e757c1be3a1d3a77fc14ea183dd56174e
-  data.tar.gz: 64cafd15ee8abe2385debadd6f95659e2a7b35a8f7dfd9c61799ba1532baa62f24775089d505937ef36e4277be1c404135cee88cb4d55cef2624c003e9a307fc
+  metadata.gz: af69d008cb08440a894f1ee58583e565dcf4994a5825fd0f57415cbd8aea1fc90bc493c47d73be7e0c5304a8651fa7cd003fbda1a22d97ac3c16e658193ebdc4
+  data.tar.gz: 4dc3acb9501663a583d921c9fef4a50074eace63b1b67ebdc1eead7507e0ffef05c78ed60047fa796c4538e937e8776c71ecd7cd52093815f80d17fb5405af9c

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    array-sort (0.1.0)
+    array-sort (0.1.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,6 +1,6 @@
 # ArraySort
 
-ArraySort adds methods in the Ruby `Array` class that provides sorting methods using a few sorting algorithms.
+ArraySort adds methods in the Ruby Array class that provides sorting methods using popular sorting algorithms.
 
 Currently, the following sorting algorithms are implemented:
  * Bubble sort _(stable)_
@@ -9,8 +9,8 @@ Currently, the following sorting algorithms are implemented:
  * Merge sort _(stable)_
  * Quicksort _(unstable)_
 
-Note that this gem does not overwrite `Array#sort`, `Array#sort!`, `Array#sort_by`, `Array#sort_by!`. Calling those
-methods will invoke the native sorting methods, which uses in-place quicksort algorithm and is unstable.
+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.
 
 ## Installation
 
@@ -40,7 +40,7 @@ change the names of the sorting methods to the following corresponding methods o
  * 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`.
+sorting methods of Array.
 
 For example, to sort an array using insertion sort:
 

data/array-sort.gemspec

@@ -10,8 +10,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Leo Liang']
   spec.email         = ['developer@leoliang.com']
 
-  spec.summary       = 'Implementations of different sorting algorithms for Arrays.'
-  spec.description   = 'Implements sorting algorithms such as merge sort, bubble sort, insertion sort, etc. for Arrays.'
+  spec.summary       = 'Implementations of popular sorting algorithms for Arrays.'
+  spec.description   = 'Implements sorting algorithms such as merge sort, bubble sort, heap sort, etc. for Arrays.'
   spec.homepage      = 'https://github.com/foxhatleo/array-sort'
   spec.license       = 'MIT'
 

data/lib/array/sort.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+#
 require 'array/sort/version'
 require 'array/sort/helper'
 require 'array/sort/merge_sort'

data/lib/array/sort/bubble_sort.rb

@@ -1,10 +1,32 @@
 # frozen_string_literal: true
 
 class Array
+  # Returns a new array created by sorting +self+, using bubble sort algorithm.
+  #
+  # Comparisons for the sort will be done using the <=> operator or using an optional code block.
+  #
+  # The block must implement a comparison between +a+ and +b+ and return an integer less than 0 when +b+ follows +a+,
+  # +0+ when +a+ and +b+ are equivalent, or an integer greater than 0 when +a+ follows +b+.
+  #
+  # The result is guaranteed to be stable. When the comparison of two elements returns +0+, the order of the elements
+  # will be preserved.
+  #
+  # @return [Array] the sorted array
   def bubble_sort(&block)
     dup.bubble_sort!(&block)
   end
 
+  # Sorts +self+ in place, using bubble sort algorithm.
+  #
+  # Comparisons for the sort will be done using the <=> operator or using an optional code block.
+  #
+  # The block must implement a comparison between +a+ and +b+ and return an integer less than 0 when +b+ follows +a+,
+  # +0+ when +a+ and +b+ are equivalent, or an integer greater than 0 when +a+ follows +b+.
+  #
+  # The result is guaranteed to be stable. When the comparison of two elements returns +0+, the order of the elements
+  # will be preserved.
+  #
+  # @return [Array] +self+
   def bubble_sort!(&block)
     return self if length <= 1
     n = length
@@ -16,6 +38,16 @@ class Array
     self
   end
 
+  # Returns a new array created by sorting +self+ with bubble sort algorithm, using a set of keys generated by mapping
+  # the values in self through the given block.
+  #
+  # The result is guaranteed to be stable. When the comparison of two elements returns +0+, the order of the elements
+  # will be preserved.
+  #
+  # If no block is given, an Enumerator is returned instead.
+  #
+  # @return [Array] if a block is given, the sorted array
+  # @return [Enumerator] if no block is given, an Enumerator
   def bubble_sort_by(&block)
     if block_given?
       dup.bubble_sort_by!(&block)
@@ -24,6 +56,16 @@ class Array
     end
   end
 
+  # Sorts +self+ in place with bubble sort algorithm, using a set of keys generated by mapping the values in self
+  # through the given block.
+  #
+  # The result is guaranteed to be stable. When the comparison of two elements returns +0+, the order of the elements
+  # will be preserved.
+  #
+  # If no block is given, an Enumerator is returned instead.
+  #
+  # @return [Array] if a block is given, the sorted array
+  # @return [Enumerator] if no block is given, an Enumerator
   def bubble_sort_by!(&_block)
     if block_given?
       bubble_sort! do |a, b|
@@ -36,6 +78,7 @@ class Array
 
   private
 
+  # @private
   def bubble_sort_check(length_checking, &block)
     new_n = 0
     (1...length_checking).each do |i|

data/lib/array/sort/heap_sort.rb

@@ -1,10 +1,32 @@
 # frozen_string_literal: true
 
 class Array
+  # Returns a new array created by sorting +self+, using heap sort algorithm.
+  #
+  # Comparisons for the sort will be done using the <=> operator or using an optional code block.
+  #
+  # The block must implement a comparison between +a+ and +b+ and return an integer less than 0 when +b+ follows +a+,
+  # +0+ when +a+ and +b+ are equivalent, or an integer greater than 0 when +a+ follows +b+.
+  #
+  # The result is not guaranteed to be stable. When the comparison of two elements returns +0+, the order of the
+  # elements is unpredictable.
+  #
+  # @return [Array] the sorted array
   def heap_sort(&block)
     dup.heap_sort!(&block)
   end
 
+  # Sorts +self+ in place, using heap sort algorithm.
+  #
+  # Comparisons for the sort will be done using the <=> operator or using an optional code block.
+  #
+  # The block must implement a comparison between +a+ and +b+ and return an integer less than 0 when +b+ follows +a+,
+  # +0+ when +a+ and +b+ are equivalent, or an integer greater than 0 when +a+ follows +b+.
+  #
+  # The result is not guaranteed to be stable. When the comparison of two elements returns +0+, the order of the
+  # elements is unpredictable.
+  #
+  # @return [Array] +self+
   def heap_sort!(&block)
     return self if length <= 1
     heapify(&block)
@@ -15,6 +37,16 @@ class Array
     self
   end
 
+  # Returns a new array created by sorting +self+ with heap sort algorithm, using a set of keys generated by mapping the
+  # values in self through the given block.
+  #
+  # The result is not guaranteed to be stable. When the comparison of two elements returns +0+, the order of the
+  # elements is unpredictable.
+  #
+  # If no block is given, an Enumerator is returned instead.
+  #
+  # @return [Array] if a block is given, the sorted array
+  # @return [Enumerator] if no block is given, an Enumerator
   def heap_sort_by(&block)
     if block_given?
       dup.heap_sort_by!(&block)
@@ -23,6 +55,16 @@ class Array
     end
   end
 
+  # Sorts +self+ in place with heap sort algorithm, using a set of keys generated by mapping the values in self through
+  # the given block.
+  #
+  # The result is not guaranteed to be stable. When the comparison of two elements returns +0+, the order of the
+  # elements is unpredictable.
+  #
+  # If no block is given, an Enumerator is returned instead.
+  #
+  # @return [Array] if a block is given, the sorted array
+  # @return [Enumerator] if no block is given, an Enumerator
   def heap_sort_by!(&_block)
     if block_given?
       heap_sort! do |a, b|
@@ -35,6 +77,7 @@ class Array
 
   private
 
+  # @private
   def heapify(&block)
     end_ = length - 1
     (length / 2 - 1).downto(0) do |start|
@@ -42,6 +85,7 @@ class Array
     end
   end
 
+  # @private
   def sift_down(start, end_, &block)
     root = start
     loop do
@@ -53,10 +97,12 @@ class Array
     end
   end
 
+  # @private
   def check_less_than_sibling(child, end_, &block)
     child + 1 <= end_ && sort_compare(self[child], self[child + 1], &block) == -1
   end
 
+  # @private
   def check_max_heap_order(root, child, &block)
     return true unless sort_compare(self[root], self[child], &block) == -1
     swap root, child

data/lib/array/sort/helper.rb

@@ -6,6 +6,7 @@ class Array
   # @param index1 [Integer] The index of the first element.
   # @param index2 [Integer] The index of the second element.
   # @return [Array]
+  # @raise [ArgumentError] If either of the two parameters is not an Integer.
   def swap(index1, index2)
     raise ArgumentError, 'Index must be an integer.' unless index1.is_a?(Integer) && index2.is_a?(Integer)
     self[index1], self[index2] = self[index2], self[index1] if index1 != index2
@@ -16,7 +17,7 @@ class Array
 
   # Compare two elements.
   #
-  # If a block is provided, it will be used to compare the two elements. If not, +<=>+ will be used.
+  # If a block is provided, it will be used to compare the two elements. If not, operator +<=>+ will be used.
   def sort_compare(element1, element2, &_block)
     if block_given?
       yield element1, element2

data/lib/array/sort/insertion_sort.rb

@@ -1,10 +1,32 @@
 # frozen_string_literal: true
 
 class Array
+  # Returns a new array created by sorting +self+, using insertion sort algorithm.
+  #
+  # Comparisons for the sort will be done using the <=> operator or using an optional code block.
+  #
+  # The block must implement a comparison between +a+ and +b+ and return an integer less than 0 when +b+ follows +a+,
+  # +0+ when +a+ and +b+ are equivalent, or an integer greater than 0 when +a+ follows +b+.
+  #
+  # The result is guaranteed to be stable. When the comparison of two elements returns +0+, the order of the elements
+  # will be preserved.
+  #
+  # @return [Array] the sorted array
   def insertion_sort(&block)
     dup.insertion_sort!(&block)
   end
 
+  # Sorts +self+ in place, using insertion sort algorithm.
+  #
+  # Comparisons for the sort will be done using the <=> operator or using an optional code block.
+  #
+  # The block must implement a comparison between +a+ and +b+ and return an integer less than 0 when +b+ follows +a+,
+  # +0+ when +a+ and +b+ are equivalent, or an integer greater than 0 when +a+ follows +b+.
+  #
+  # The result is guaranteed to be stable. When the comparison of two elements returns +0+, the order of the elements
+  # will be preserved.
+  #
+  # @return [Array] +self+
   def insertion_sort!(&block)
     return self if length <= 1
     (1...length).each do |i|
@@ -16,6 +38,16 @@ class Array
     self
   end
 
+  # Returns a new array created by sorting +self+ with insertion sort algorithm, using a set of keys generated by
+  # mapping the values in self through the given block.
+  #
+  # The result is guaranteed to be stable. When the comparison of two elements returns +0+, the order of the elements
+  # will be preserved.
+  #
+  # If no block is given, an Enumerator is returned instead.
+  #
+  # @return [Array] if a block is given, the sorted array
+  # @return [Enumerator] if no block is given, an Enumerator
   def insertion_sort_by(&block)
     if block_given?
       dup.insertion_sort_by!(&block)
@@ -24,6 +56,16 @@ class Array
     end
   end
 
+  # Sorts +self+ in place with insertion sort algorithm, using a set of keys generated by mapping the values in self
+  # through the given block.
+  #
+  # The result is guaranteed to be stable. When the comparison of two elements returns +0+, the order of the elements
+  # will be preserved.
+  #
+  # If no block is given, an Enumerator is returned instead.
+  #
+  # @return [Array] if a block is given, the sorted array
+  # @return [Enumerator] if no block is given, an Enumerator
   def insertion_sort_by!(&_block)
     if block_given?
       insertion_sort! do |a, b|

data/lib/array/sort/merge_sort.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 class Array
+  # Returns a new array created by sorting +self+, using merge sort algorithm.
+  #
+  # Comparisons for the sort will be done using the <=> operator or using an optional code block.
+  #
+  # The block must implement a comparison between +a+ and +b+ and return an integer less than 0 when +b+ follows +a+,
+  # +0+ when +a+ and +b+ are equivalent, or an integer greater than 0 when +a+ follows +b+.
+  #
+  # The result is guaranteed to be stable. When the comparison of two elements returns +0+, the order of the elements
+  # will be preserved.
+  #
+  # @return [Array] the sorted array
   def merge_sort(&block)
     return dup if length <= 1
     divided_parts = merge_sort_divide
@@ -9,10 +20,31 @@ class Array
     merge_sort_merge part_a_sorted, part_b_sorted, &block
   end
 
+  # Sorts +self+ in place, using merge sort algorithm.
+  #
+  # Comparisons for the sort will be done using the <=> operator or using an optional code block.
+  #
+  # The block must implement a comparison between +a+ and +b+ and return an integer less than 0 when +b+ follows +a+,
+  # +0+ when +a+ and +b+ are equivalent, or an integer greater than 0 when +a+ follows +b+.
+  #
+  # The result is guaranteed to be stable. When the comparison of two elements returns +0+, the order of the elements
+  # will be preserved.
+  #
+  # @return [Array] +self+
   def merge_sort!(&block)
     become_clone_of merge_sort(&block)
   end
 
+  # Returns a new array created by sorting +self+ with merge sort algorithm, using a set of keys generated by mapping
+  # the values in self through the given block.
+  #
+  # The result is guaranteed to be stable. When the comparison of two elements returns +0+, the order of the elements
+  # will be preserved.
+  #
+  # If no block is given, an Enumerator is returned instead.
+  #
+  # @return [Array] if a block is given, the sorted array
+  # @return [Enumerator] if no block is given, an Enumerator
   def merge_sort_by(&_block)
     if block_given?
       merge_sort do |a, b|
@@ -23,6 +55,16 @@ class Array
     end
   end
 
+  # Sorts +self+ in place with merge sort algorithm, using a set of keys generated by mapping the values in self through
+  # the given block.
+  #
+  # The result is guaranteed to be stable. When the comparison of two elements returns +0+, the order of the elements
+  # will be preserved.
+  #
+  # If no block is given, an Enumerator is returned instead.
+  #
+  # @return [Array] if a block is given, the sorted array
+  # @return [Enumerator] if no block is given, an Enumerator
   def merge_sort_by!(&block)
     if block_given?
       become_clone_of merge_sort_by(&block)
@@ -33,6 +75,7 @@ class Array
 
   private
 
+  # @private
   def merge_sort_divide
     mid = length / 2
     part_a = self[0, mid]
@@ -40,6 +83,7 @@ class Array
     [part_a, part_b]
   end
 
+  # @private
   def merge_sort_merge(part_a, part_b, &block)
     result = []
     while part_a.length.positive? && part_b.length.positive?

data/lib/array/sort/quick_sort.rb

@@ -1,16 +1,48 @@
 # frozen_string_literal: true
 
 class Array
+  # Returns a new array created by sorting +self+, using quicksort algorithm.
+  #
+  # Comparisons for the sort will be done using the <=> operator or using an optional code block.
+  #
+  # The block must implement a comparison between +a+ and +b+ and return an integer less than 0 when +b+ follows +a+,
+  # +0+ when +a+ and +b+ are equivalent, or an integer greater than 0 when +a+ follows +b+.
+  #
+  # The result is not guaranteed to be stable. When the comparison of two elements returns +0+, the order of the
+  # elements is unpredictable.
+  #
+  # @return [Array] the sorted array
   def quick_sort(&block)
     return dup if length <= 1
     left, right = self[1..-1].partition { |y| sort_compare(first, y, &block).positive? }
     left.quick_sort + [first] + right.quick_sort
   end
 
+  # Sorts +self+ in place, using quicksort algorithm.
+  #
+  # Comparisons for the sort will be done using the <=> operator or using an optional code block.
+  #
+  # The block must implement a comparison between +a+ and +b+ and return an integer less than 0 when +b+ follows +a+,
+  # +0+ when +a+ and +b+ are equivalent, or an integer greater than 0 when +a+ follows +b+.
+  #
+  # The result is not guaranteed to be stable. When the comparison of two elements returns +0+, the order of the
+  # elements is unpredictable.
+  #
+  # @return [Array] +self+
   def quick_sort!(&block)
     become_clone_of quick_sort(&block)
   end
 
+  # Returns a new array created by sorting +self+ with quicksort algorithm, using a set of keys generated by mapping
+  # the values in self through the given block.
+  #
+  # The result is not guaranteed to be stable. When the comparison of two elements returns +0+, the order of the
+  # elements is unpredictable.
+  #
+  # If no block is given, an Enumerator is returned instead.
+  #
+  # @return [Array] if a block is given, the sorted array
+  # @return [Enumerator] if no block is given, an Enumerator
   def quick_sort_by(&_block)
     if block_given?
       quick_sort do |a, b|
@@ -21,6 +53,16 @@ class Array
     end
   end
 
+  # Sorts +self+ in place with quicksort algorithm, using a set of keys generated by mapping the values in self through
+  # the given block.
+  #
+  # The result is not guaranteed to be stable. When the comparison of two elements returns +0+, the order of the
+  # elements is unpredictable.
+  #
+  # If no block is given, an Enumerator is returned instead.
+  #
+  # @return [Array] if a block is given, the sorted array
+  # @return [Enumerator] if no block is given, an Enumerator
   def quick_sort_by!(&block)
     if block_given?
       become_clone_of quick_sort_by(&block)

data/lib/array/sort/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: array-sort
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Leo Liang
@@ -52,8 +52,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
-description: Implements sorting algorithms such as merge sort, bubble sort, insertion
-  sort, etc. for Arrays.
+description: Implements sorting algorithms such as merge sort, bubble sort, heap sort,
+  etc. for Arrays.
 email:
 - developer@leoliang.com
 executables: []
@@ -102,5 +102,5 @@ rubyforge_project:
 rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
-summary: Implementations of different sorting algorithms for Arrays.
+summary: Implementations of popular sorting algorithms for Arrays.
 test_files: []