fat_core 3.0.0 → 4.0.0

data/lib/fat_core/hash.rb

@@ -1,8 +1,47 @@
+# The FatCore extensions to Hash provide a handful of generally useful methods
+# on Ruby Hash objects.
+#
+# You can get these with:
+#
+# ```
+# require 'fat_core/hash'
+# ```
+#
+# It provides a couple of methods for manipulating the keys of a Hash:
+# `#remap_keys` for translating the current set of keys to a new set provided by
+# a Hash of old to new keys, and `#replace_keys` for doing a similar operation
+# with an Array of new keys. Along the same line, the method `#keys_with_value`
+# will return the keys in a Hash equal to the given value of any of an Array of
+# values.
+#
+# It also provides a method for deleting all entries in a Hash whose value match
+# a single value or any one of an Array of values in `#delete_with_value`
+#
+# Finally, it provides an `#each_pair`-like method, `#each_pair_with_flags`,
+# that yields each key-value pair of the Hash along with two boolean flags that
+# indicate whether the element is the first or last in the Hash.
 module FatCore
-
   module Hash
-    # Yield each key-value pair in the Hash together with boolean flags that
-    # indicate whether the item is the first or last yielded.
+    # @group Enumerable Extensions
+    #
+    # Yield each key-value pair in the Hash together with two boolean flags that
+    # indicate whether the item is the first or last item in the Hash.
+    #
+    # @example
+    #   {a: 1, b: 2, c: 3}.each_pair_with_flags do |k, val, first, last|
+    #     print "#{k} => #{val}"
+    #     print " is first" if first
+    #     print " is last" if last
+    #     print " is nothing special" if !first && !last
+    #     print "\n"
+    #   end
+    #
+    #   #=> output:
+    #   a => 1 is first
+    #   b => 2 is nothing special
+    #   c => 3 is last
+    #
+    # @return [Hash] return self
     def each_pair_with_flags
       last_k = size - 1
       k = 0
@@ -12,10 +51,40 @@ module FatCore
         yield(key, val, first, last)
         k += 1
       end
+      self
+    end
+
+    # @group Deletion
+    #
+    # Remove from the hash all keys that have values == to given value or that
+    # include the given value if the hash has an Enumerable for a value
+    #
+    # @example
+    #   h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
+    #   h.delete_with_value(2) #=> { a: 1, c: 3, e: 1 }
+    #   h.delete_with_value([1, 3]) #=> { b: 2, d: 2 }
+    #
+    # @param v [Object, Enumerable<Object>] value to test for
+    # @return [Hash] hash having entries === v or including v deleted
+    def delete_with_value(v)
+      keys_with_value(v).each do |k|
+        delete(k)
+      end
+      self
     end
 
+    # @group Key Manipulation
+    #
     # Return all keys in hash that have a value == to the given value or have an
     # Enumerable value that includes the given value.
+    #
+    # @example
+    #   h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
+    #   h.keys_with_value(2) #=> [:b, :d]
+    #   h.keys_with_value([1, 3]) #=> [:a, :c, :e]
+    #
+    # @param val [Object, Enumerable<Object>] value to test for
+    # @return [Array<Object>] the keys with value or values v
     def keys_with_value(val)
       result = []
       each_pair do |k, v|
@@ -26,16 +95,16 @@ module FatCore
       result
     end
 
-    # Remove from the hash all keys that have values == to given value or that
-    # include the given value if the hash has an Enumerable for a value
-    def delete_with_value(v)
-      keys_with_value(v).each do |k|
-        delete(k)
-      end
-      self
-    end
-
-    # Change each key of this Hash to its value in key_map
+    # Change each key of this Hash to its value in `key_map`. Keys not appearing in
+    # the `key_map` remain in the result Hash.
+    #
+    # @example
+    #   h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
+    #   key_map = { a: 'alpha', b: 'beta' }
+    #   h.remap_keys(key_map) #=> {"alpha"=>1, "beta"=>2, :c=>3, :d=>2, :e=>1}
+    #
+    # @param key_map [Hash] hash mapping old keys to new
+    # @return [Hash] new hash with remapped keys
     def remap_keys(key_map = {})
       new_hash = {}
       each_pair do |key, val|
@@ -48,7 +117,17 @@ module FatCore
       new_hash
     end
 
-    # Change the keys of this Hash to new_keys, an array of keys
+    # Change the keys of this Hash to new_keys, an array of keys of the same size
+    # as the Array self.keys.
+    #
+    # @example
+    #   h = { a: 1, b: 2, c: 3, d: 2, e: 1 }
+    #   nk = [:z, :y, :x, :w, :v]
+    #   h.replace_keys(nk) #=> {:z=>1, :y=>2, :x=>3, :w=>2, :v=>1}
+    #
+    # @raise [ArgumentError] if new_keys.size != self.keys.size
+    # @param new_keys [Array<Object>] replacement keys
+    # @return [Hash]
     def replace_keys(new_keys)
       unless keys.size == new_keys.size
         raise ArgumentError, 'replace_keys: new keys size differs from key size'
@@ -58,4 +137,8 @@ module FatCore
   end
 end
 
-Hash.include FatCore::Hash
+class Hash
+  include FatCore::Hash
+  # @!parse include FatCore::Hash
+  # @!parse extend FatCore::Hash::ClassMethods
+end

data/lib/fat_core/kernel.rb

@@ -1,6 +1,19 @@
 require 'fat_core/numeric'
 
 module Kernel
+  # Run the given block and report the time it took to execute in
+  # hour-minute-second form.
+  #
+  # @example
+  #   result = time_it 'Fibbonacci' do
+  #     Fibbonacci.fib(30)
+  #   end
+  #   puts "For 30 its #{result}"
+  #   => "Ran Fibonacci in 30:23"
+  #
+  # @param name [String, #to_s] an optional name to use for block in timing
+  #   message.
+  # @return [Object] whatever the block returns
   def time_it(name = 'block', &block)
     start = Time.now
     result = yield block

data/lib/fat_core/nil.rb

@@ -1,17 +1,31 @@
 module FatCore
   module NilClass
-    def entitle
+    # Allow nils to respond to #as_string like String and Symbol
+    #
+    # @return [String] empty string
+    def as_string
       ''
     end
+    alias entitle as_string
 
+    # Allow nils to respond to #tex_quote for use in TeX documents
+    #
+    # @return [String] empty string
     def tex_quote
       ''
     end
 
+    # Allow nils to respond to #commas like String and Numeric
+    #
+    # @return [String] empty string
     def commas(_places = nil)
       ''
     end
   end
 end
 
-NilClass.include FatCore::NilClass
+class NilClass
+  include FatCore::NilClass
+  # @!parse include FatCore::NilClass
+  # @!parse extend FatCore::NilClass::ClassMethods
+end

data/lib/fat_core/numeric.rb

@@ -1,7 +1,16 @@
+require 'active_support/core_ext/object/blank'
+
 module FatCore
   module Numeric
     # Return the signum function for this number, i.e., 1 for a positive number,
     # 0 for zero, and -1 for a negative number.
+    #
+    # @example
+    #   -55.signum #=> -1
+    #   0.signum   #=> 0
+    #   55.signum  #=> 1
+    #
+    # @return [Integer] -1, 0, or 1 for negative, zero or positive self
     def signum
       if positive?
         1
@@ -13,28 +22,40 @@ module FatCore
     end
 
     # Convert this number into a string and insert grouping commas into the
-    # whole number part and round the decimal part to +places+ decimal places,
-    # with the number of places being zero for an integer and 4 for a
-    # non-integer.
+    # whole number part and round the decimal part to `places` decimal places,
+    # with the default number of places being zero for an integer and 4 for a
+    # non-integer. The fractional part is padded with zeroes on the right to
+    # come out to `places` digits after the decimal place.
+    #
+    # @example
+    #   9324089.56.commas #=> '9,324,089.56'
+    #   88883.14159.commas #=>'88,883.1416'
+    #   88883.14159.commas(2) #=>'88,883.14'
+    #
+    # @param places [Integer] number of decimal place to round to
+    # @return [String]
     def commas(places = nil)
-      # By default, use zero places for whole numbers; four places for
-      # numbers containing a fractional part to 4 places.
-      if places.nil?
-        places =
-          if abs.modulo(1).round(4) > 0.0
-            4
-          else
-            0
-          end
-      end
       group(places, ',')
     end
 
     # Convert this number into a string and insert grouping delimiter character,
-    # +delim+ into the whole number part and round the decimal part to +places+
-    # decimal places, with the number of places being zero for an integer and 4
-    # for a non-integer.
-    def group(places = 0, delim = ',')
+    # `delim` into the whole number part and round the decimal part to `places`
+    # decimal places, with the default number of places being zero for an
+    # integer and 4 for a non-integer. The fractional part is padded with zeroes
+    # on the right to come out to `places` digits after the decimal place. This
+    # is the same as #commas, but allows the delimiter to be any string.
+    #
+    # @example
+    #   9324089.56.group          #=> '9,324,089.56'
+    #   9324089.56.group(4)       #=> '9,324,089.5600'
+    #   88883.14159.group         #=>'88,883.1416'
+    #   88883.14159.group(2)      #=>'88,883.14'
+    #   88883.14159.group(2, '_') #=>'88_883.14'
+    #
+    # @param places [Integer] number of decimal place to round to
+    # @param delim [String] use delim as group separator
+    # @return [String]
+    def group(places = nil, delim = ',')
       # Return number as a string with embedded commas
       # for nice printing; round to places places after
       # the decimal
@@ -43,43 +64,69 @@ module FatCore
       # less than 1 (to ensure that really small numbers round to 0.0)
       return to_s if abs > 1.0 && to_s =~ /e/
 
-      str = to_f.round(places).to_s
+      # Round if places given
+      str =
+        if places.nil?
+          whole? ? to_i.to_s : to_f.to_s
+        else
+          to_f.round(places).to_s
+        end
 
-      # Break the number into parts
-      str =~ /^(-)?(\d*)((\.)?(\d*))?$/
-      neg = $1 || ''
-      whole = $2
-      frac = $5
+      # Break the number into parts; underscores are possible in all components.
+      str =~ /\A([-+])?([\d_]*)((\.)?([\d_]*))?([eE][+-]?[\d_]+)?\z/
+      sig = $1 || ''
+      whole = $2 ? $2.delete('_') : ''
+      frac = $5 || ''
+      exp = $6 || ''
 
       # Pad out the fractional part with zeroes to the right
-      n_zeroes = [places - frac.length, 0].max
-      frac += '0' * n_zeroes if n_zeroes.positive?
+      unless places.nil?
+        n_zeroes = [places - frac.length, 0].max
+        frac += '0' * n_zeroes if n_zeroes.positive?
+      end
 
       # Place the commas in the whole part only
       whole = whole.reverse
       whole.gsub!(/([0-9]{3})/, "\\1#{delim}")
       whole.gsub!(/#{Regexp.escape(delim)}$/, '')
       whole.reverse!
-      if frac.nil? || places <= 0
-        neg + whole
+      if frac.blank? # || places <= 0
+        sig + whole + exp
       else
-        neg + whole + '.' + frac
+        sig + whole + '.' + frac + exp
       end
     end
 
     # Return whether this is a whole number.
+    #
+    # @example
+    #   23.45.whole? #=> false
+    #   23.whole?    #=> true
+    #
+    # @return [Boolean] is self whole?
     def whole?
       floor == self
     end
 
     # Return an Integer type, but only if the fractional part of self is zero;
     # otherwise just return self.
+    #
+    # @example
+    #   45.98.int_if_whole #=> 45.98
+    #   45.000.int_if_whole #=> 45
+    #
+    # @return [Numeric, Integer]
     def int_if_whole
       whole? ? floor : self
     end
 
-    # Convert a number of seconds into a string of the form HH:MM:SS.dd, that is
-    # to hours, minutes and seconds.
+    # Convert self, regarded as a number of seconds, into a string of the form
+    # HH:MM:SS.dd, that is to hours, minutes and seconds and fractions of seconds.
+    #
+    # @example
+    #   5488.secs_to_hms #=> "01:31:28"
+    #
+    # @return [String] formatted as HH:MM:SS.dd
     def secs_to_hms
       frac = self % 1
       mins, secs = divmod(60)
@@ -91,11 +138,16 @@ module FatCore
       end
     end
 
-    # Allow erb documents to directly interpolate numbers
+    # Quote self for use in TeX documents.  Since number components are not
+    # special to TeX, this just applies `#to_s`
     def tex_quote
       to_s
     end
   end
 end
 
-Numeric.include FatCore::Numeric
+class Numeric
+  include FatCore::Numeric
+  # @!parse include FatCore::Numeric
+  # @!parse extend FatCore::Numeric::ClassMethods
+end

data/lib/fat_core/range.rb

@@ -1,7 +1,30 @@
+# FatCore extends the Range class with methods that
+#
+# 1. provide some set operations operations on Ranges, union, intersection, and
+#    difference,
+# 2. test for overlapping and contiguity between Ranges,
+# 3. test for whether one Range is a subset or superset of another,
+# 3. join contiguous Ranges,
+# 4. find whether a set of Ranges spans a large range, and if not, to return
+#    a set of Ranges that represent gaps in the coverage or overlaps in
+#    coverage,
+# 5. provide a definition for sorting Ranges based on sorting by the min values
+#    and sizes of the Ranges.
 module FatCore
   module Range
-    # Return a range that concatenates this range with other; return nil
-    # if the ranges are not contiguous.
+    # @group Operations
+
+    # Return a range that concatenates this range with other if it is contiguous
+    # with this range on the left or right; return nil if the ranges are not
+    # contiguous.
+    #
+    # @example
+    #    (0..3).join(4..8) #=> (0..8)
+    #
+    # @param other [Range] the Range to join to this range
+    # @return [Range, nil] this range joined to other
+    #
+    # @see contiguous? For the definition of "contiguous"
     def join(other)
       if left_contiguous?(other)
         ::Range.new(min, other.max)
@@ -10,55 +33,112 @@ module FatCore
       end
     end
 
-    # Is self on the left of and contiguous to other?
-    def left_contiguous?(other)
-      if max.respond_to?(:succ)
-        max.succ == other.min
+    # If this range is not spanned by the `ranges` collectively, return an Array
+    # of ranges representing the gaps in coverage.  The `ranges` can over-cover
+    # this range on the left or right without affecting the result, that is,
+    # each range in the returned array of gap ranges will always be subsets of
+    # this range.
+    #
+    # If the `ranges` span this range, return an empty array.
+    #
+    # @example
+    #   (0..10).gaps([(0..3), (5..6), (9..10)])  #=> [(4..4), (7..8)]
+    #   (0..10).gaps([(-4..3), (5..6), (9..15)]) #=> [(4..4), (7..8)]
+    #   (0..10).gaps([(-4..3), (4..6), (7..15)]) #=> [] ranges span this one
+    #   (0..10).gaps([(-4..-3), (11..16), (17..25)]) #=> [(0..10)] no overlap
+    #   (0..10).gaps([])                             #=> [(0..10)] no overlap
+    #
+    # @param ranges [Array<Range>]
+    # @return [Array<Range>]
+    def gaps(ranges)
+      if ranges.empty?
+        [clone]
+      elsif spanned_by?(ranges)
+        []
       else
-        max == other.min
+        ranges = ranges.sort_by(&:min)
+        gaps = []
+        cur_point = min
+        ranges.each do |rr|
+          break if rr.min > max
+          if rr.min > cur_point
+            start_point = cur_point
+            end_point = rr.min.pred
+            gaps << (start_point..end_point)
+            cur_point = rr.max.succ
+          elsif rr.max >= cur_point
+            cur_point = rr.max.succ
+          end
+        end
+        gaps << (cur_point..max) if cur_point <= max
+        gaps
       end
     end
 
-    # Is self on the right of and contiguous to other?
-    def right_contiguous?(other)
-      if other.max.respond_to?(:succ)
-        other.max.succ == min
+    # Within this range return an Array of Ranges representing the overlaps
+    # among the given Array of Ranges `ranges`. If there are no overlaps, return
+    # an empty array. Don't consider overlaps in the `ranges` that occur outside
+    # of self.
+    #
+    # @example
+    #  (0..10).overlaps([(-4..4), (2..7), (5..12)]) => [(2..4), (5..7)]
+    #
+    # @param ranges [Array<Range>] ranges to search for overlaps
+    # @return [Array<Range>] overlaps with ranges but inside this Range
+    def overlaps(ranges)
+      if ranges.empty? || spanned_by?(ranges)
+        []
       else
-        other.max == min
+        ranges = ranges.sort_by(&:min)
+        overlaps = []
+        cur_point = nil
+        ranges.each do |rr|
+          # Skip ranges outside of self
+          next if rr.max < min || rr.min > max
+          # Initialize cur_point to max of first range
+          if cur_point.nil?
+            cur_point = rr.max
+            next
+          end
+          # We are on the second or later range
+          if rr.min < cur_point
+            start_point = rr.min
+            end_point = cur_point
+            overlaps << (start_point..end_point)
+          end
+          cur_point = rr.max
+        end
+        overlaps
       end
     end
 
-    def contiguous?(other)
-      left_contiguous?(other) || right_contiguous?(other)
-    end
-
-    def subset_of?(other)
-      min >= other.min && max <= other.max
-    end
-
-    def proper_subset_of?(other)
-      min > other.min && max < other.max
-    end
-
-    def superset_of?(other)
-      min <= other.min && max >= other.max
-    end
-
-    def proper_superset_of?(other)
-      min < other.min && max > other.max
-    end
-
-    def overlaps?(other)
-      (cover?(other.min) || cover?(other.max) ||
-       other.cover?(min) || other.cover?(max))
-    end
-
+    # Return a Range that represents the intersection between this range and the
+    # `other` range.  If there is no intersection, return nil.
+    #
+    # @example
+    #   (0..10) & (5..20)             #=> (5..10)
+    #   (0..10).intersection((5..20)) #=> (5..10)
+    #   (0..10) & (15..20)            #=> nil
+    #
+    # @param other [Range] the Range self is intersected with
+    # @return [Range, nil] a Range representing the intersection
     def intersection(other)
       return nil unless overlaps?(other)
       ([min, other.min].max..[max, other.max].min)
     end
     alias & intersection
 
+    # Return a Range that represents the union between this range and the
+    # `other` range.  If there is no overlap and self is not contiguous with
+    # `other`, return `nil`.
+    #
+    # @example
+    #   (0..10) + (5..20)       #=> (0..20)
+    #   (0..10).union((5..20))  #=> (0..20)
+    #   (0..10) + (15..20)      #=> nil
+    #
+    # @param other [Range] the Range self is union-ed with
+    # @return [Range, nil] a Range representing the union
     def union(other)
       return nil unless overlaps?(other) || contiguous?(other)
       ([min, other.min].min..[max, other.max].max)
@@ -93,29 +173,165 @@ module FatCore
     end
     alias - difference
 
-    # Return whether any of the ranges that are within self overlap one
-    # another
-    def has_overlaps_within?(ranges)
-      result = false
-      unless ranges.empty?
-        ranges.each do |r1|
-          next unless overlaps?(r1)
-          result =
-            ranges.any? do |r2|
-            r1.object_id != r2.object_id && overlaps?(r2) &&
-              r1.overlaps?(r2)
-          end
-          return true if result
-        end
+    # Allow erb or erubis documents to directly interpolate a Range.
+    #
+    # @return [String]
+    def tex_quote
+      to_s
+    end
+
+    # @group Queries
+
+    # Is self on the left of and contiguous to other?  Whether one range is
+    # "contiguous" to another has two cases:
+    #
+    # 1. If the elements of the Range on the left respond to the #succ method
+    #    (that is, its values are discrete values such as Integers or Dates)
+    #    test whether the succ to the max value of the Range on the left is
+    #    equal to the min value of the Range on the right.
+    # 2. If the elements of the Range on the left do not respond to the #succ
+    #    method (that is, its values are continuous values such as Floats) test
+    #    whether the max value of the Range on the left is equal to the min
+    #    value of the Range on the right
+    #
+    # @example
+    #    (0..10).left_contiguous((11..20))           #=> true
+    #    (11..20).left_contiguous((0..10))           #=> false, but right_contiguous
+    #    (0.5..3.145).left_contiguous((3.145..18.4)) #=> true
+    #    (0.5..3.145).left_contiguous((3.146..18.4)) #=> false
+    #
+    # @param other [Range] other range to test for contiguity
+    # @return [Boolean] is self left_contiguous with other
+    def left_contiguous?(other)
+      if max.respond_to?(:succ)
+        max.succ == other.min
+      else
+        max == other.min
       end
-      result
+    end
+
+    # Is self on the right of and contiguous to other?  Whether one range is
+    # "contiguous" to another has two cases:
+    #
+    # 1. If the elements of the Range on the left respond to the #succ method
+    #    (that is, its values are discrete values such as Integers or Dates)
+    #    test whether the succ to the max value of the Range on the left is
+    #    equal to the min value of the Range on the right.
+    # 2. If the elements of the Range on the left do not respond to the #succ
+    #    method (that is, its values are continuous values such as Floats) test
+    #    whether the max value of the Range on the left is equal to the min
+    #    value of the Range on the right
+    #
+    # @example
+    #    (11..20).right_contiguous((0..10))           #=> true
+    #    (0..10).right_contiguous((11..20))           #=> false, but left_contiguous
+    #    (3.145..12.3).right_contiguous((0.5..3.145)) #=> true
+    #    (3.146..12.3).right_contiguous((0.5..3.145)) #=> false
+    #
+    # @param other [Range] other range to test for contiguity
+    # @return [Boolean] is self right_contiguous with other
+    def right_contiguous?(other)
+      if other.max.respond_to?(:succ)
+        other.max.succ == min
+      else
+        other.max == min
+      end
+    end
+
+    # Is self contiguous to other either on the left or on the right? First, the
+    # two ranges are sorted by their min values, and the range with the lowest
+    # min value is considered to be on the "left" and the other range on the
+    # "right". Whether one range is "contiguous" to another then has two cases:
+    #
+    # 1. If the max element of the Range on the left respond to the #succ method
+    #    (that is, its value is a discrete value such as Integer or Date)
+    #    test whether the succ to the max value of the Range on the left is
+    #    equal to the min value of the Range on the right.
+    # 2. If the max element of the Range on the left does not respond to the
+    #    #succ method (that is, its values are continuous values such as Floats)
+    #    test whether the max value of the Range on the left is equal to the min
+    #    value of the Range on the right
+    #
+    # @example
+    #   (0..10).contiguous?((11..20))           #=> true
+    #   (11..20).contiguous?((0..10))           #=> true, right_contiguous
+    #   (0..10).contiguous?((15..20))           #=> false
+    #   (3.145..12.3).contiguous?((0.5..3.145)) #=> true
+    #   (3.146..12.3).contiguous?((0.5..3.145)) #=> false
+    #
+    # @param other [Range] other range to test for contiguity
+    # @return [Boolean] is self contiguous with other
+    def contiguous?(other)
+      left_contiguous?(other) || right_contiguous?(other)
+    end
+
+    # Return whether self is contained within `other` range, even if their
+    # boundaries touch.
+    #
+    # @param other [Range] the containing range
+    # @return [Boolean] is self within other
+    def subset_of?(other)
+      min >= other.min && max <= other.max
+    end
+
+    # Return whether self is contained within `other` range, without their
+    # boundaries touching.
+    #
+    # @param other [Range] the containing range
+    # @return [Boolean] is self wholly within other
+    def proper_subset_of?(other)
+      min > other.min && max < other.max
+    end
+
+    # Return whether self contains `other` range, even if their
+    # boundaries touch.
+    #
+    # @param other [Range] the contained range
+    # @return [Boolean] does self contain other
+    def superset_of?(other)
+      min <= other.min && max >= other.max
+    end
+
+    # Return whether self contains `other` range, without their
+    # boundaries touching.
+    #
+    # @param other [Range] the contained range
+    # @return [Boolean] does self wholly contain other
+    def proper_superset_of?(other)
+      min < other.min && max > other.max
+    end
+
+    # Return whether self overlaps with other Range.
+    #
+    # @param other [Range] range to test for overlap with self
+    # @return [Boolean] is there an overlap?
+    def overlaps?(other)
+      (cover?(other.min) || cover?(other.max) ||
+       other.cover?(min) || other.cover?(max))
+    end
+
+    # Return whether any of the `ranges` that overlap self have overlaps among one
+    # another.
+    #
+    # This does the same thing as `Range.overlaps_among?`, except that it filters
+    # the `ranges` to only those overlapping self before testing for overlaps
+    # among them.
+    #
+    # @param ranges [Array<Range>] ranges to test for overlaps
+    # @return [Boolean] were there overlaps among ranges?
+    def overlaps_among?(ranges)
+      iranges = ranges.select { |r| overlaps?(r) }
+      ::Range.overlaps_among?(iranges)
     end
 
     # Return true if the given ranges collectively cover this range
-    # without overlaps.
+    # without overlaps and without gaps.
+    #
+    # @param ranges [Array<Range>]
+    # @return [Boolean]
     def spanned_by?(ranges)
       joined_range = nil
-      ranges.sort_by(&:min).each do |r|
+      ranges.sort.each do |r|
         unless joined_range
           joined_range = r
           next
@@ -130,69 +346,55 @@ module FatCore
       end
     end
 
-    # If this range is not spanned by the ranges collectively, return an array
-    # of ranges representing the gaps in coverage.  Otherwise return an empty
-    # array.
-    def gaps(ranges)
-      if ranges.empty?
-        [clone]
-      elsif spanned_by?(ranges)
-        []
-      else
-        ranges = ranges.sort_by(&:min)
-        gaps = []
-        cur_point = min
-        ranges.each do |rr|
-          break if rr.min > max
-          if rr.min > cur_point
-            start_point = cur_point
-            end_point = rr.min.pred
-            gaps << (start_point..end_point)
-            cur_point = rr.max.succ
-          elsif rr.max >= cur_point
-            cur_point = rr.max.succ
-          end
-        end
-        gaps << (cur_point..max) if cur_point <= max
-        gaps
-      end
+    include Comparable
+
+    # @group Sorting
+
+    # Compare this range with other first by min values, then by max values.
+    #
+    # This causes a sort of Ranges with Comparable elements to sort from left to
+    # right on the number line, then for Ranges that start on the same number, from
+    # smallest to largest.
+    #
+    # @example
+    #   (4..8) <=> (5..7) #=> -1
+    #   (4..8) <=> (4..7) #=> 1
+    #   (4..8) <=> (4..8) #=> 0
+    #
+    # @param other [Range] range to compare self with
+    # @return [-1, 0, 1] if self is less, equal, or greater than other
+    def <=>(other)
+      [min, max] <=> [other.min, other.max]
     end
 
-    # Similar to gaps, but within this range return the /overlaps/ among the
-    # given ranges.  If there are no overlaps, return an empty array. Don't
-    # consider overlaps in the ranges that occur outside of self.
-    def overlaps(ranges)
-      if ranges.empty? || spanned_by?(ranges)
-        []
-      else
-        ranges = ranges.sort_by(&:min)
-        overlaps = []
-        cur_point = nil
-        ranges.each do |rr|
-          # Skip ranges outside of self
-          next if rr.max < min || rr.min > max
-          # Initialize cur_point to max of first range
-          if cur_point.nil?
-            cur_point = rr.max
-            next
+    module ClassMethods
+      # Return whether any of the `ranges` overlap one another
+      #
+      # @param ranges [Array<Range>] ranges to test for overlaps
+      # @return [Boolean] were there overlaps among ranges?
+      def overlaps_among?(ranges)
+        result = false
+        unless ranges.empty?
+          ranges.each do |r1|
+            result = ranges.any? do |r2|
+              r1.object_id != r2.object_id && r1.overlaps?(r2)
+            end
+            return true if result
           end
-          # We are on the second or later range
-          if rr.min < cur_point
-            start_point = rr.min
-            end_point = cur_point
-            overlaps << (start_point..end_point)
-          end
-          cur_point = rr.max
         end
-        overlaps
+        result
       end
     end
 
-    # Allow erb documents can directly interpolate ranges
-    def tex_quote
-      to_s
+    # @private
+    def self.included(base)
+      base.extend(ClassMethods)
     end
   end
 end
 
-Range.include FatCore::Range
+class Range
+  include FatCore::Range
+  # @!parse include FatCore::Range
+  # @!parse extend FatCore::Range::ClassMethods
+end