Add Range.intersection and Range#intersection

Find the shared region of multiple ranges. Returns nil if ranges
do not overlap. Works with any comparable type (integers, floats,
dates, strings, etc.).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: trans

HISTORY.md

@@ -15,6 +15,8 @@ Changes:
   * Add `Array#indexes` / `Array#index_all` to find all matching indexes. (PR#294)
   * Add `String#dashcase` for kebab-case conversion. (PR#297)
   * Add `Binding#caller_locations`.
+  * Add `Range.intersection` and `Range#intersection` for finding the shared
+    region of multiple ranges. Works with any comparable type.
   * Add `Kernel#tee` — block-less method chaining via Tee/Functor, replaces `tap` override.
   * Add `Tee` as alias for `Functor` (gradual rename).
   * Rename `Hash#to_proc` to `Hash#setter` (avoids clash with Ruby 2.3's `Hash#to_proc`

lib/core/facets/range/intersection.rb

@@ -0,0 +1,42 @@
+class Range
+
+  # Returns the intersection of two or more ranges — the region they
+  # all share. Returns nil if the ranges do not overlap.
+  #
+  # Works with any comparable type: integers, floats, dates, strings, etc.
+  #
+  # Examples
+  #
+  #     Range.intersection(1..10, 5..15)         #=> 5..10
+  #     Range.intersection(1..5, 3..7, 4..9)     #=> 4..5
+  #     Range.intersection(1..3, 5..7)            #=> nil
+  #     Range.intersection(1.0..5.0, 2.5..4.5)   #=> 2.5..4.5
+  #
+  # Also available as an instance method:
+  #
+  #     (1..10).intersection(5..15)              #=> 5..10
+  #
+  # CREDIT: Trans
+
+  def self.intersection(*ranges)
+    return nil if ranges.empty?
+    ranges.reduce do |result, r|
+      return nil unless result.overlap?(r)
+      new_first = result.first > r.first ? result.first : r.first
+      new_last  = result.last  < r.last  ? result.last  : r.last
+      new_first..new_last
+    end
+  end
+
+  # Returns the intersection of this range with one or more other ranges.
+  # Returns nil if the ranges do not overlap.
+  #
+  #     (1..10).intersection(5..15)        #=> 5..10
+  #     (1..10).intersection(5..15, 8..20) #=> 8..10
+  #     (1..3).intersection(5..7)          #=> nil
+  #
+  def intersection(*others)
+    Range.intersection(self, *others)
+  end
+
+end

test/core/range/test_intersection.rb

@@ -0,0 +1,45 @@
+covers 'facets/range/intersection'
+
+test_case Range do
+
+  class_method :intersection do
+
+    test "two overlapping ranges" do
+      Range.intersection(1..10, 5..15).assert == 5..10
+    end
+
+    test "three overlapping ranges" do
+      Range.intersection(1..5, 3..7, 4..9).assert == 4..5
+    end
+
+    test "non-overlapping ranges" do
+      Range.intersection(1..3, 5..7).assert == nil
+    end
+
+    test "floats" do
+      Range.intersection(1.0..5.0, 2.5..4.5).assert == 2.5..4.5
+    end
+
+    test "identical ranges" do
+      Range.intersection(1..5, 1..5).assert == 1..5
+    end
+
+    test "one range contains the other" do
+      Range.intersection(1..10, 3..5).assert == 3..5
+    end
+
+  end
+
+  method :intersection do
+
+    test "instance method" do
+      (1..10).intersection(5..15).assert == 5..10
+    end
+
+    test "multiple arguments" do
+      (1..10).intersection(5..15, 8..20).assert == 8..10
+    end
+
+  end
+
+end