rbs 2.8.4 → 3.8.1

data/core/range.rbs

@@ -4,7 +4,7 @@
 #
 # You can create an Range object explicitly with:
 #
-# *   A [range literal](doc/syntax/literals_rdoc.html#label-Range+Literals):
+# *   A [range literal](rdoc-ref:syntax/literals.rdoc@Range+Literals):
 #
 #         # Ranges that use '..' to include the given end value.
 #         (1..4).to_a      # => [1, 2, 3, 4]
@@ -13,15 +13,13 @@
 #         (1...4).to_a     # => [1, 2, 3]
 #         ('a'...'d').to_a # => ["a", "b", "c"]
 #
+# *   Method Range.new:
 #
-# A range may be created using method Range.new:
-#
-#     # Ranges that by default include the given end value.
-#     Range.new(1, 4).to_a     # => [1, 2, 3, 4]
-#     Range.new('a', 'd').to_a # => ["a", "b", "c", "d"]
-#     # Ranges that use third argument +exclude_end+ to exclude the given end value.
-#     Range.new(1, 4, true).to_a     # => [1, 2, 3]
-#     Range.new('a', 'd', true).to_a # => ["a", "b", "c"]
+#     # Ranges that by default include the given end value. Range.new(1, 4).to_a
+#         # => [1, 2, 3, 4] Range.new('a', 'd').to_a # => ["a", "b", "c", "d"] #
+#     Ranges that use third argument `exclude_end` to exclude the given end
+#     value. Range.new(1, 4, true).to_a     # => [1, 2, 3] Range.new('a', 'd',
+#     true).to_a # => ["a", "b", "c"]
 #
 # ## Beginless Ranges
 #
@@ -42,8 +40,12 @@
 # A beginless range may be used to slice an array:
 #
 #     a = [1, 2, 3, 4]
-#     r = (..2) # => nil...2
-#     a[r]      # => [1, 2]
+#     # Include the third array element in the slice
+#     r = (..2)  # => nil..2
+#     a[r]       # => [1, 2, 3]
+#     # Exclude the third array element from the slice
+#     r = (...2) # => nil...2
+#     a[r]       # => [1, 2]
 #
 # Method `each` for a beginless range raises an exception.
 #
@@ -58,9 +60,9 @@
 #
 #     Range.new(1, nil) # => 1..
 #
-# The literal for  an endless range may be written with either two dots or
-# three. The range has the same elements, either way. But note that the two are
-# not equal:
+# The literal for an endless range may be written with either two dots or three.
+# The range has the same elements, either way. But note that the two are not
+# equal:
 #
 #     r0 = (1..)           # => 1..
 #     r1 = (1...)          # => 1...
@@ -84,11 +86,20 @@
 #     end
 #     a # => [2, 4, 6, 8, 10]
 #
+# A range can be both beginless and endless.  For literal beginless, endless
+# ranges, at least the beginning or end of the range must be given as an
+# explicit nil value. It is recommended to use an explicit nil beginning and
+# implicit nil end, since that is what Ruby uses for Range#inspect:
+#
+#     (nil..)    # => (nil..)
+#     (..nil)    # => (nil..)
+#     (nil..nil) # => (nil..)
+#
 # ## Ranges and Other Classes
 #
 # An object may be put into a range if its class implements instance method
-# `<=>`. Ruby core classes that do so include Array, Complex, File::Stat, Float,
-# Integer, Kernel, Module, Numeric, Rational, String, Symbol, and Time.
+# `#<=>`. Ruby core classes that do so include Array, Complex, File::Stat,
+# Float, Integer, Kernel, Module, Numeric, Rational, String, Symbol, and Time.
 #
 # Example:
 #
@@ -108,7 +119,6 @@
 # *   Included from module Enumerable: #each_entry, #each_with_index,
 #     #each_with_object, #each_slice, #each_cons, and #reverse_each.
 #
-#
 # Example:
 #
 #     a = []
@@ -118,13 +128,12 @@
 # ## Ranges and User-Defined Classes
 #
 # A user-defined class that is to be used in a range must implement instance
-# `<=>`; see [Integer#<=>](Integer.html#label-method-i-3C-3D-3E). To make
-# iteration available, it must also implement instance method `succ`; see
-# Integer#succ.
+# method `#<=>`; see Integer#<=>. To make iteration available, it must also
+# implement instance method `succ`; see Integer#succ.
 #
-# The class below implements both `<=>` and `succ`, and so can be used both to
+# The class below implements both `#<=>` and `succ`, and so can be used both to
 # construct ranges and to iterate over them. Note that the Comparable module is
-# included so the `==` method is defined in terms of `<=>`.
+# included so the `==` method is defined in terms of `#<=>`.
 #
 #     # Represent a string of 'X' characters.
 #     class Xs
@@ -156,117 +165,102 @@
 #
 # First, what's elsewhere. Class Range:
 #
-# *   Inherits from [class
-#     Object](Object.html#class-Object-label-What-27s+Here).
-# *   Includes [module
-#     Enumerable](Enumerable.html#module-Enumerable-label-What-27s+Here), which
+# *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
+# *   Includes [module Enumerable](rdoc-ref:Enumerable@What-27s+Here), which
 #     provides dozens of additional methods.
 #
-#
 # Here, class Range provides methods that are useful for:
 #
-# *   [Creating a Range](#class-Range-label-Methods+for+Creating+a+Range)
-# *   [Querying](#class-Range-label-Methods+for+Querying)
-# *   [Comparing](#class-Range-label-Methods+for+Comparing)
-# *   [Iterating](#class-Range-label-Methods+for+Iterating)
-# *   [Converting](#class-Range-label-Methods+for+Converting)
-#
+# *   [Creating a Range](rdoc-ref:Range@Methods+for+Creating+a+Range)
+# *   [Querying](rdoc-ref:Range@Methods+for+Querying)
+# *   [Comparing](rdoc-ref:Range@Methods+for+Comparing)
+# *   [Iterating](rdoc-ref:Range@Methods+for+Iterating)
+# *   [Converting](rdoc-ref:Range@Methods+for+Converting)
+# *   [Methods for Working with
+#     JSON](rdoc-ref:Range@Methods+for+Working+with+JSON)
 #
 # ### Methods for Creating a Range
 #
-#     ::new
-# :       Returns a new range.
-#
-#
+# *   ::new: Returns a new range.
 #
 # ### Methods for Querying
 #
-#     #begin
-# :       Returns the begin value given for `self`.
-#
-#     #bsearch
-# :       Returns an element from `self` selected by a binary search.
-#
-#     #count
-# :       Returns a count of elements in `self`.
-#
-#     #end
-# :       Returns the end value given for `self`.
-#
-#     #exclude_end?
-# :       Returns whether the end object is excluded.
-#
-#     #first
-# :       Returns the first elements of `self`.
-#
-#     #hash
-# :       Returns the integer hash code.
-#
-#     #last
-# :       Returns the last elements of `self`.
-#
-#     #max
-# :       Returns the maximum values in `self`.
-#
-#     #min
-# :       Returns the minimum values in `self`.
-#
-#     #minmax
-# :       Returns the minimum and maximum values in `self`.
-#
-#     #size
-# :       Returns the count of elements in `self`.
-#
-#
+# *   #begin: Returns the begin value given for `self`.
+# *   #bsearch: Returns an element from `self` selected by a binary search.
+# *   #count: Returns a count of elements in `self`.
+# *   #end: Returns the end value given for `self`.
+# *   #exclude_end?: Returns whether the end object is excluded.
+# *   #first: Returns the first elements of `self`.
+# *   #hash: Returns the integer hash code.
+# *   #last: Returns the last elements of `self`.
+# *   #max: Returns the maximum values in `self`.
+# *   #min: Returns the minimum values in `self`.
+# *   #minmax: Returns the minimum and maximum values in `self`.
+# *   #size: Returns the count of elements in `self`.
 #
 # ### Methods for Comparing
 #
-#     [#==](#method-i-3D-3D)
-# :       Returns whether a given object is equal to `self` (uses #==).
-#
-#     #===
-# :       Returns whether the given object is between the begin and end values.
-#
-#     #cover?
-# :       Returns whether a given object is within `self`.
-#
-#     #eql?
-# :       Returns whether a given object is equal to `self` (uses #eql?).
-#
-#     #include? (aliased as #member?)
-# :       Returns whether a given object is an element of `self`.
-#
-#
+# *   #==: Returns whether a given object is equal to `self` (uses #==).
+# *   #===: Returns whether the given object is between the begin and end
+#     values.
+# *   #cover?: Returns whether a given object is within `self`.
+# *   #eql?: Returns whether a given object is equal to `self` (uses #eql?).
+# *   #include? (aliased as #member?): Returns whether a given object is an
+#     element of `self`.
 #
 # ### Methods for Iterating
 #
-#     #%
-# :       Requires argument `n`; calls the block with each `n`-th element of
-#         `self`.
-#
-#     #each
-# :       Calls the block with each element of `self`.
+# *   #%: Requires argument `n`; calls the block with each `n`-th element of
+#     `self`.
+# *   #each: Calls the block with each element of `self`.
+# *   #step: Takes optional argument `n` (defaults to 1); calls the block with
+#     each `n`-th element of `self`.
 #
-#     #step
-# :       Takes optional argument `n` (defaults to 1); calls the block with each
-#         `n`-th element of `self`.
+# ### Methods for Converting
 #
+# *   #inspect: Returns a string representation of `self` (uses #inspect).
+# *   #to_a (aliased as #entries): Returns elements of `self` in an array.
+# *   #to_s: Returns a string representation of `self` (uses #to_s).
 #
+# ### Methods for Working with JSON
 #
-# ### Methods for Converting
+# *   ::json_create: Returns a new Range object constructed from the given
+#     object.
+# *   #as_json: Returns a 2-element hash representing `self`.
+# *   #to_json: Returns a JSON string representing `self`.
 #
-#     #inspect
-# :       Returns a string representation of `self` (uses #inspect).
+# To make these methods available:
 #
-#     #to_a (aliased as #entries)
-# :       Returns elements of `self` in an array.
-#
-#     #to_s
-# :       Returns a string representation of `self` (uses #to_s).
+#     require 'json/add/range'
 #
 class Range[out Elem] < Object
   include Enumerable[Elem]
 
+  # <!--
+  #   rdoc-file=range.c
+  #   - %(n) {|element| ... } -> self
+  #   - %(n)                  -> enumerator or arithmetic_sequence
+  # -->
+  # Same as #step (but doesn't provide default value for `n`). The method is
+  # convenient for experssive producing of Enumerator::ArithmeticSequence.
+  #
+  #     array = [0, 1, 2, 3, 4, 5, 6]
+  #
+  #     # slice each second element:
+  #     seq = (0..) % 2 #=> ((0..).%(2))
+  #     array[seq] #=> [0, 2, 4, 6]
+  #     # or just
+  #     array[(0..) % 2] #=> [0, 2, 4, 6]
+  #
+  # Note that due to operator precedence in Ruby, parentheses are mandatory around
+  # range in this case:
+  #
+  #     (0..7) % 2 #=> ((0..7).%(2)) -- as expected
+  #     0..7 % 2 #=> 0..1 -- parsed as 0..(7 % 2)
+  #
+  def %: (Numeric | int n) -> Enumerator[Elem, self]
+       | (Numeric | int n) { (Elem element) -> void } -> self
+
   # <!--
   #   rdoc-file=range.c
   #   - self == other -> true or false
@@ -278,7 +272,6 @@ class Range[out Elem] < Object
   # *   `other.end == self.end`.
   # *   `other.exclude_end? == self.exclude_end?`.
   #
-  #
   # Otherwise returns `false`.
   #
   #     r = (1..5)
@@ -441,9 +434,49 @@ class Range[out Elem] < Object
   # Returns `false` if either:
   #
   # *   The begin value of `self` is larger than its end value.
-  # *   An internal call to `<=>` returns `nil`; that is, the operands are not
+  # *   An internal call to `#<=>` returns `nil`; that is, the operands are not
   #     comparable.
   #
+  # Beginless ranges cover all values of the same type before the end, excluding
+  # the end for exclusive ranges. Beginless ranges cover ranges that end before
+  # the end of the beginless range, or at the end of the beginless range for
+  # inclusive ranges.
+  #
+  #     (..2).cover?(1)     # => true
+  #     (..2).cover?(2)     # => true
+  #     (..2).cover?(3)     # => false
+  #     (...2).cover?(2)    # => false
+  #     (..2).cover?("2")   # => false
+  #     (..2).cover?(..2)   # => true
+  #     (..2).cover?(...2)  # => true
+  #     (..2).cover?(.."2") # => false
+  #     (...2).cover?(..2)  # => false
+  #
+  # Endless ranges cover all values of the same type after the beginning. Endless
+  # exclusive ranges do not cover endless inclusive ranges.
+  #
+  #     (2..).cover?(1)     # => false
+  #     (2..).cover?(3)     # => true
+  #     (2...).cover?(3)    # => true
+  #     (2..).cover?(2)     # => true
+  #     (2..).cover?("2")   # => false
+  #     (2..).cover?(2..)   # => true
+  #     (2..).cover?(2...)  # => true
+  #     (2..).cover?("2"..) # => false
+  #     (2...).cover?(2..)  # => false
+  #     (2...).cover?(3...) # => true
+  #     (2...).cover?(3..)  # => false
+  #     (3..).cover?(2..)   # => false
+  #
+  # Ranges that are both beginless and endless cover all values and ranges, and
+  # return true for all arguments, with the exception that beginless and endless
+  # exclusive ranges do not cover endless inclusive ranges.
+  #
+  #     (nil...).cover?(Object.new) # => true
+  #     (nil...).cover?(nil...)     # => true
+  #     (nil..).cover?(nil...)      # => true
+  #     (nil...).cover?(nil..)      # => false
+  #     (nil...).cover?(1..)        # => false
   #
   # Related: Range#include?.
   #
@@ -554,8 +587,6 @@ class Range[out Elem] < Object
   #
   # Related: Range#cover?.
   #
-  # Range#member? is an alias for Range#include?.
-  #
   def include?: (untyped obj) -> bool
 
   # <!--
@@ -637,7 +668,7 @@ class Range[out Elem] < Object
   #   - max {|a, b| ... } -> object
   #   - max(n) {|a, b| ... } -> array
   # -->
-  # Returns the maximum value in `self`, using method `<=>` or a given block for
+  # Returns the maximum value in `self`, using method `#<=>` or a given block for
   # comparison.
   #
   # With no argument and no block given, returns the maximum-valued element of
@@ -661,7 +692,6 @@ class Range[out Elem] < Object
   # *   Then, sequentially, with the so-far maximum value and the next element of
   #     `self`.
   #
-  #
   # To illustrate:
   #
   #     (1..4).max {|a, b| p [a, b]; a <=> b } # => 4
@@ -704,13 +734,11 @@ class Range[out Elem] < Object
   #         (1...1).max  {|a, b| -(a <=> b) }    # => nil
   #         (1...1).max(2)  {|a, b| -(a <=> b) } # => []
   #
-  #
   # Raises an exception if either:
   #
   # *   `self` is a endless range: `(1..)`.
   # *   A block is given and `self` is a beginless range.
   #
-  #
   # Related: Range#min, Range#minmax.
   #
   def max: () -> Elem
@@ -725,7 +753,7 @@ class Range[out Elem] < Object
   #   - min {|a, b| ... } -> object
   #   - min(n) {|a, b| ... } -> array
   # -->
-  # Returns the minimum value in `self`, using method `<=>` or a given block for
+  # Returns the minimum value in `self`, using method `#<=>` or a given block for
   # comparison.
   #
   # With no argument and no block given, returns the minimum-valued element of
@@ -749,7 +777,6 @@ class Range[out Elem] < Object
   # *   Then, sequentially, with the so-far minimum value and the next element of
   #     `self`.
   #
-  #
   # To illustrate:
   #
   #     (1..4).min {|a, b| p [a, b]; a <=> b } # => 1
@@ -792,13 +819,11 @@ class Range[out Elem] < Object
   #         (1...1).min  {|a, b| -(a <=> b) }    # => nil
   #         (1...1).min(2)  {|a, b| -(a <=> b) } # => []
   #
-  #
   # Raises an exception if either:
   #
   # *   `self` is a beginless range: `(..4)`.
   # *   A block is given and `self` is an endless range.
   #
-  #
   # Related: Range#max, Range#minmax.
   #
   def min: () -> Elem
@@ -806,6 +831,92 @@ class Range[out Elem] < Object
          | (Integer n) -> ::Array[Elem]
          | (Integer n) { (Elem a, Elem b) -> Integer } -> ::Array[Elem]
 
+  # <!--
+  #   rdoc-file=range.c
+  #   - overlap?(range) -> true or false
+  # -->
+  # Returns `true` if `range` overlaps with `self`, `false` otherwise:
+  #
+  #     (0..2).overlap?(1..3) #=> true
+  #     (0..2).overlap?(3..4) #=> false
+  #     (0..).overlap?(..0)   #=> true
+  #
+  # With non-range argument, raises TypeError.
+  #
+  #     (1..3).overlap?(1)         # TypeError
+  #
+  # Returns `false` if an internal call to `#<=>` returns `nil`; that is, the
+  # operands are not comparable.
+  #
+  #     (1..3).overlap?('a'..'d')  # => false
+  #
+  # Returns `false` if `self` or `range` is empty. "Empty range" means that its
+  # begin value is larger than, or equal for an exclusive range, its end value.
+  #
+  #     (4..1).overlap?(2..3)      # => false
+  #     (4..1).overlap?(..3)       # => false
+  #     (4..1).overlap?(2..)       # => false
+  #     (2...2).overlap?(1..2)     # => false
+  #
+  #     (1..4).overlap?(3..2)      # => false
+  #     (..4).overlap?(3..2)       # => false
+  #     (1..).overlap?(3..2)       # => false
+  #     (1..2).overlap?(2...2)     # => false
+  #
+  # Returns `false` if the begin value one of `self` and `range` is larger than,
+  # or equal if the other is an exclusive range, the end value of the other:
+  #
+  #     (4..5).overlap?(2..3)      # => false
+  #     (4..5).overlap?(2...4)     # => false
+  #
+  #     (1..2).overlap?(3..4)      # => false
+  #     (1...3).overlap?(3..4)     # => false
+  #
+  # Returns `false` if the end value one of `self` and `range` is larger than, or
+  # equal for an exclusive range, the end value of the other:
+  #
+  #     (4..5).overlap?(2..3)      # => false
+  #     (4..5).overlap?(2...4)     # => false
+  #
+  #     (1..2).overlap?(3..4)      # => false
+  #     (1...3).overlap?(3..4)     # => false
+  #
+  # Note that the method wouldn't make any assumptions about the beginless range
+  # being actually empty, even if its upper bound is the minimum possible value of
+  # its type, so all this would return `true`:
+  #
+  #     (...-Float::INFINITY).overlap?(...-Float::INFINITY) # => true
+  #     (..."").overlap?(..."") # => true
+  #     (...[]).overlap?(...[]) # => true
+  #
+  # Even if those ranges are effectively empty (no number can be smaller than
+  # `-Float::INFINITY`), they are still considered overlapping with themselves.
+  #
+  # Related: Range#cover?.
+  #
+  def overlap?: (Range[untyped]) -> bool
+
+  # <!--
+  #   rdoc-file=range.c
+  #   - reverse_each {|element| ... } -> self
+  #   - reverse_each                  -> an_enumerator
+  # -->
+  # With a block given, passes each element of `self` to the block in reverse
+  # order:
+  #
+  #     a = []
+  #     (1..4).reverse_each {|element| a.push(element) } # => 1..4
+  #     a # => [4, 3, 2, 1]
+  #
+  #     a = []
+  #     (1...4).reverse_each {|element| a.push(element) } # => 1...4
+  #     a # => [3, 2, 1]
+  #
+  # With no block given, returns an enumerator.
+  #
+  def reverse_each: () { (Elem) -> void } -> self
+                  | () -> ::Enumerator[Elem, self]
+
   # <!--
   #   rdoc-file=range.c
   #   - size -> non_negative_integer or Infinity or nil
@@ -816,7 +927,12 @@ class Range[out Elem] < Object
   #     (1..4).size      # => 4
   #     (1...4).size     # => 3
   #     (1..).size       # => Infinity
-  #     ('a'..'z').size  #=> nil
+  #     ('a'..'z').size  # => nil
+  #
+  # If `self` is not iterable, raises an exception:
+  #
+  #     (0.5..2.5).size  # TypeError
+  #     (..1).size       # TypeError
   #
   # Related: Range#count.
   #
@@ -825,43 +941,86 @@ class Range[out Elem] < Object
 
   # <!--
   #   rdoc-file=range.c
-  #   - step(n = 1) {|element| ... } -> self
-  #   - step(n = 1)                  -> enumerator
+  #   - step(s = 1) {|element| ... } -> self
+  #   - step(s = 1)                  -> enumerator/arithmetic_sequence
   # -->
-  # Iterates over the elements of `self`.
+  # Iterates over the elements of range in steps of `s`. The iteration is
+  # performed by `+` operator:
   #
-  # With a block given and no argument, calls the block each element of the range;
-  # returns `self`:
+  #     (0..6).step(2) { puts _1 } #=> 1..5
+  #     # Prints: 0, 2, 4, 6
   #
-  #     a = []
-  #     (1..5).step {|element| a.push(element) } # => 1..5
-  #     a # => [1, 2, 3, 4, 5]
-  #     a = []
-  #     ('a'..'e').step {|element| a.push(element) } # => "a".."e"
-  #     a # => ["a", "b", "c", "d", "e"]
+  #     # Iterate between two dates in step of 1 day (24 hours)
+  #     (Time.utc(2022, 2, 24)..Time.utc(2022, 3, 1)).step(24*60*60) { puts _1 }
+  #     # Prints:
+  #     #   2022-02-24 00:00:00 UTC
+  #     #   2022-02-25 00:00:00 UTC
+  #     #   2022-02-26 00:00:00 UTC
+  #     #   2022-02-27 00:00:00 UTC
+  #     #   2022-02-28 00:00:00 UTC
+  #     #   2022-03-01 00:00:00 UTC
   #
-  # With a block given and a positive integer argument `n` given, calls the block
-  # with element `0`, element `n`, element `2n`, and so on:
+  # If ` + step` decreases the value, iteration is still performed when step
+  # `begin` is higher than the `end`:
   #
-  #     a = []
-  #     (1..5).step(2) {|element| a.push(element) } # => 1..5
-  #     a # => [1, 3, 5]
-  #     a = []
-  #     ('a'..'e').step(2) {|element| a.push(element) } # => "a".."e"
-  #     a # => ["a", "c", "e"]
+  #     (0..6).step(-2) { puts _1 }
+  #     # Prints nothing
+  #
+  #     (6..0).step(-2) { puts _1 }
+  #     # Prints: 6, 4, 2, 0
   #
-  # With no block given, returns an enumerator, which will be of class
-  # Enumerator::ArithmeticSequence if `self` is numeric; otherwise of class
-  # Enumerator:
+  #     (Time.utc(2022, 3, 1)..Time.utc(2022, 2, 24)).step(-24*60*60) { puts _1 }
+  #     # Prints:
+  #     #   2022-03-01 00:00:00 UTC
+  #     #   2022-02-28 00:00:00 UTC
+  #     #   2022-02-27 00:00:00 UTC
+  #     #   2022-02-26 00:00:00 UTC
+  #     #   2022-02-25 00:00:00 UTC
+  #     #   2022-02-24 00:00:00 UTC
   #
-  #     e = (1..5).step(2) # => ((1..5).step(2))
-  #     e.class            # => Enumerator::ArithmeticSequence
-  #     ('a'..'e').step # => #<Enumerator: ...>
+  # When the block is not provided, and range boundaries and step are Numeric, the
+  # method returns Enumerator::ArithmeticSequence.
   #
-  # Related: Range#%.
+  #     (1..5).step(2) # => ((1..5).step(2))
+  #     (1.0..).step(1.5) #=> ((1.0..).step(1.5))
+  #     (..3r).step(1/3r) #=> ((..3/1).step((1/3)))
   #
-  def step: (?Integer n) { (Elem arg0) -> untyped } -> self
-          | (?Integer n) -> ::Enumerator[Elem, void]
+  # Enumerator::ArithmeticSequence can be further used as a value object for
+  # iteration or slicing of collections (see Array#[]). There is a convenience
+  # method #% with behavior similar to `step` to produce arithmetic sequences more
+  # expressively:
+  #
+  #     # Same as (1..5).step(2)
+  #     (1..5) % 2 # => ((1..5).%(2))
+  #
+  # In a generic case, when the block is not provided, Enumerator is returned:
+  #
+  #     ('a'..).step('b')         #=> #<Enumerator: "a"..:step("b")>
+  #     ('a'..).step('b').take(3) #=> ["a", "ab", "abb"]
+  #
+  # If `s` is not provided, it is considered `1` for ranges with numeric `begin`:
+  #
+  #     (1..5).step { p _1 }
+  #     # Prints: 1, 2, 3, 4, 5
+  #
+  # For non-Numeric ranges, step absence is an error:
+  #
+  #     (Time.utc(2022, 3, 1)..Time.utc(2022, 2, 24)).step { p _1 }
+  #     # raises: step is required for non-numeric ranges (ArgumentError)
+  #
+  # For backward compatibility reasons, String ranges support the iteration both
+  # with string step and with integer step. In the latter case, the iteration is
+  # performed by calculating the next values with String#succ:
+  #
+  #     ('a'..'e').step(2) { p _1 }
+  #     # Prints: a, c, e
+  #     ('a'..'e').step { p _1 }
+  #     # Default step 1; prints: a, b, c, d, e
+  #
+  def step: (?Numeric | int) -> Enumerator[Elem, self]
+          | (?Numeric | int) { (Elem element) -> void } -> self
+          | (untyped) -> Enumerator[Elem, self]
+          | (untyped) { (Elem element) -> void } -> self
 
   # <!--
   #   rdoc-file=range.c
@@ -891,11 +1050,10 @@ class Range[out Elem] < Object
   # Returns `true` if and only if:
   #
   # *   `other` is a range.
-  # *   `other.begin eql? self.begin`.
-  # *   `other.end eql? self.end`.
+  # *   `other.begin.eql?(self.begin)`.
+  # *   `other.end.eql?(self.end)`.
   # *   `other.exclude_end? == self.exclude_end?`.
   #
-  #
   # Otherwise returns `false`.
   #
   #     r = (1..5)
@@ -945,7 +1103,5 @@ class Range[out Elem] < Object
   #
   # Related: Range#cover?.
   #
-  # Range#member? is an alias for Range#include?.
-  #
   def member?: (untyped obj) -> bool
 end