core/range.rbs in rbs-2.0.0 vs core/range.rbs in rbs-2.1.0
- old
+ new
@@ -1,226 +1,951 @@
-# A `Range` represents an interval—a set of values with a beginning and an
-# end. Ranges may be constructed using the *s* `..` *e* and *s* `...` *e*
-# literals, or with [::new](Range#method-c-new).
-# Ranges constructed using `..` run from the beginning to the end
-# inclusively. Those created using `...` exclude the end value. When used
-# as an iterator, ranges return each value in the sequence.
+# <!-- rdoc-file=range.c -->
+# A Range object represents a collection of values that are between given begin
+# and end values.
#
-# ```ruby
-# (-1..-5).to_a #=> []
-# (-5..-1).to_a #=> [-5, -4, -3, -2, -1]
-# ('a'..'e').to_a #=> ["a", "b", "c", "d", "e"]
-# ('a'...'e').to_a #=> ["a", "b", "c", "d"]
-# ```
+# You can create an Range object explicitly with:
#
+# * A [range literal](doc/syntax/literals_rdoc.html#label-Range+Literals):
#
-# An “endless range” represents a semi-infinite range. Literal notation
-# for an endless range is:
+# # Ranges that use '..' to include the given end value.
+# (1..4).to_a # => [1, 2, 3, 4]
+# ('a'..'d').to_a # => ["a", "b", "c", "d"]
+# # Ranges that use '...' to exclude the given end value.
+# (1...4).to_a # => [1, 2, 3]
+# ('a'...'d').to_a # => ["a", "b", "c"]
#
-# (1..)
-# # or similarly
-# (1...)
#
-# Which is equivalent to
+# A range may be created using method Range.new:
#
-# ```ruby
-# (1..nil) # or similarly (1...nil)
-# Range.new(1, nil) # or Range.new(1, nil, true)
-# ```
+# # 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"]
#
-# Endless ranges are useful, for example, for idiomatic slicing of arrays:
+# ## Beginless Ranges
#
-# [1, 2, 3, 4, 5][2...] # => [3, 4, 5]
+# A *beginless* *range* has a definite end value, but a `nil` begin value. Such
+# a range includes all values up to the end value.
#
-# Some implementation details:
+# r = (..4) # => nil..4
+# r.begin # => nil
+# r.include?(-50) # => true
+# r.include?(4) # => true
#
-# - `end` of endless range is `nil` ;
+# r = (...4) # => nil...4
+# r.include?(4) # => false
#
-# - `each` of endless range enumerates infinite sequence (may be useful
-# in combination with
-# [Enumerable\#take\_while](https://ruby-doc.org/core-2.6.3/Enumerable.html#method-i-take_while)
-# or similar methods);
+# Range.new(nil, 4) # => nil..4
+# Range.new(nil, 4, true) # => nil...4
#
-# - `(1..)` and `(1...)` are not equal, although technically
-# representing the same sequence.
+# A beginless range may be used to slice an array:
#
+# a = [1, 2, 3, 4]
+# r = (..2) # => nil...2
+# a[r] # => [1, 2]
#
-# Ranges can be constructed using any objects that can be compared using
-# the `<=>` operator. Methods that treat the range as a sequence (\#each
-# and methods inherited from
-# [Enumerable](https://ruby-doc.org/core-2.6.3/Enumerable.html) ) expect
-# the begin object to implement a `succ` method to return the next object
-# in sequence. The [step](Range#method-i-step) and
-# [include?](Range#method-i-include-3F) methods
-# require the begin object to implement `succ` or to be numeric.
+# Method `each` for a beginless range raises an exception.
#
-# In the `Xs` class below both `<=>` and `succ` are implemented so `Xs`
-# can be used to construct ranges. Note that the
-# [Comparable](https://ruby-doc.org/core-2.6.3/Comparable.html) module is
-# included so the `==` method is defined in terms of `<=>` .
+# ## Endless Ranges
#
-# ```ruby
-# class Xs # represent a string of 'x's
-# include Comparable
-# attr :length
-# def initialize(n)
-# @length = n
-# end
-# def succ
-# Xs.new(@length + 1)
-# end
-# def <=>(other)
-# @length <=> other.length
-# end
-# def to_s
-# sprintf "%2d #{inspect}", @length
-# end
-# def inspect
-# 'x' * @length
-# end
-# end
-# ```
+# An *endless* *range* has a definite begin value, but a `nil` end value. Such a
+# range includes all values from the begin value.
#
-# An example of using `Xs` to construct a range:
+# r = (1..) # => 1..
+# r.end # => nil
+# r.include?(50) # => true
#
-# ```ruby
-# r = Xs.new(3)..Xs.new(6) #=> xxx..xxxxxx
-# r.to_a #=> [xxx, xxxx, xxxxx, xxxxxx]
-# r.member?(Xs.new(5)) #=> true
-# ```
+# 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:
+#
+# r0 = (1..) # => 1..
+# r1 = (1...) # => 1...
+# r0.begin == r1.begin # => true
+# r0.end == r1.end # => true
+# r0 == r1 # => false
+#
+# An endless range may be used to slice an array:
+#
+# a = [1, 2, 3, 4]
+# r = (2..) # => 2..
+# a[r] # => [3, 4]
+#
+# Method `each` for an endless range calls the given block indefinitely:
+#
+# a = []
+# r = (1..)
+# r.each do |i|
+# a.push(i) if i.even?
+# break if i > 10
+# end
+# a # => [2, 4, 6, 8, 10]
+#
+# ## 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.
+#
+# Example:
+#
+# t0 = Time.now # => 2021-09-19 09:22:48.4854986 -0500
+# t1 = Time.now # => 2021-09-19 09:22:56.0365079 -0500
+# t2 = Time.now # => 2021-09-19 09:23:08.5263283 -0500
+# (t0..t2).include?(t1) # => true
+# (t0..t1).include?(t2) # => false
+#
+# A range can be iterated over only if its elements implement instance method
+# `succ`. Ruby core classes that do so include Integer, String, and Symbol (but
+# not the other classes mentioned above).
+#
+# Iterator methods include:
+#
+# * In Range itself: #each, #step, and #%
+# * Included from module Enumerable: #each_entry, #each_with_index,
+# #each_with_object, #each_slice, #each_cons, and #reverse_each.
+#
+#
+# Example:
+#
+# a = []
+# (1..4).each {|i| a.push(i) }
+# a # => [1, 2, 3, 4]
+#
+# ## 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.
+#
+# 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 `<=>`.
+#
+# # Represent a string of 'X' characters.
+# class Xs
+# include Comparable
+# attr_accessor :length
+# def initialize(n)
+# @length = n
+# end
+# def succ
+# Xs.new(@length + 1)
+# end
+# def <=>(other)
+# @length <=> other.length
+# end
+# def to_s
+# sprintf "%2d #{inspect}", @length
+# end
+# def inspect
+# 'X' * @length
+# end
+# end
+#
+# r = Xs.new(3)..Xs.new(6) #=> XXX..XXXXXX
+# r.to_a #=> [XXX, XXXX, XXXXX, XXXXXX]
+# r.include?(Xs.new(5)) #=> true
+# r.include?(Xs.new(7)) #=> false
+#
+# ## What's Here
+#
+# 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
+# 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)
+#
+#
+# ### Methods for Creating a 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`.
+#
+#
+#
+# ### 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`.
+#
+#
+#
+# ### 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`.
+#
+# #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).
+#
class Range[out Elem] < Object
include Enumerable[Elem]
+ # <!--
+ # rdoc-file=range.c
+ # - self == other -> true or false
+ # -->
+ # Returns `true` if and only if:
+ #
+ # * `other` is a range.
+ # * `other.begin == self.begin`.
+ # * `other.end == self.end`.
+ # * `other.exclude_end? == self.exclude_end?`.
+ #
+ #
+ # Otherwise returns `false`.
+ #
+ # r = (1..5)
+ # r == (1..5) # => true
+ # r = Range.new(1, 5)
+ # r == 'foo' # => false
+ # r == (2..5) # => false
+ # r == (1..4) # => false
+ # r == (1...5) # => false
+ # r == Range.new(1, 5, true) # => false
+ #
+ # Note that even with the same argument, the return values of #== and #eql? can
+ # differ:
+ #
+ # (1..2) == (1..2.0) # => true
+ # (1..2).eql? (1..2.0) # => false
+ #
+ # Related: Range#eql?.
+ #
def ==: (untyped obj) -> bool
+ # <!--
+ # rdoc-file=range.c
+ # - self === object -> true or false
+ # -->
+ # Returns `true` if `object` is between `self.begin` and `self.end`. `false`
+ # otherwise:
+ #
+ # (1..4) === 2 # => true
+ # (1..4) === 5 # => false
+ # (1..4) === 'a' # => false
+ # (1..4) === 4 # => true
+ # (1...4) === 4 # => false
+ # ('a'..'d') === 'c' # => true
+ # ('a'..'d') === 'e' # => false
+ #
+ # A case statement uses method `===`, and so:
+ #
+ # case 79
+ # when (1..50)
+ # "low"
+ # when (51..75)
+ # "medium"
+ # when (76..100)
+ # "high"
+ # end # => "high"
+ #
+ # case "2.6.5"
+ # when ..."2.4"
+ # "EOL"
+ # when "2.4"..."2.5"
+ # "maintenance"
+ # when "2.5"..."3.0"
+ # "stable"
+ # when "3.1"..
+ # "upcoming"
+ # end # => "stable"
+ #
def ===: (untyped obj) -> bool
- # Returns the object that defines the beginning of the range.
+ # <!--
+ # rdoc-file=range.c
+ # - self.begin -> object
+ # -->
+ # Returns the object that defines the beginning of `self`.
#
- # ```ruby
- # (1..10).begin #=> 1
- # ```
- def begin: () -> Elem # Begin-less ranges have type of Range[Integer?]
+ # (1..4).begin # => 1
+ # (..2).begin # => nil
+ #
+ # Related: Range#first, Range#end.
+ #
+ def begin: () -> Elem
+ # <!--
+ # rdoc-file=range.c
+ # - bsearch {|obj| block } -> value
+ # -->
+ # Returns an element from `self` selected by a binary search.
+ #
+ # See [Binary Searching](rdoc-ref:bsearch.rdoc).
+ #
def bsearch: () -> ::Enumerator[Elem, Elem?]
| () { (Elem) -> (true | false) } -> Elem?
| () { (Elem) -> ::Integer } -> Elem?
+ # <!--
+ # rdoc-file=range.c
+ # - cover?(object) -> true or false
+ # - cover?(range) -> true or false
+ # -->
+ # Returns `true` if the given argument is within `self`, `false` otherwise.
+ #
+ # With non-range argument `object`, evaluates with `<=` and `<`.
+ #
+ # For range `self` with included end value (`#exclude_end? == false`), evaluates
+ # thus:
+ #
+ # self.begin <= object <= self.end
+ #
+ # Examples:
+ #
+ # r = (1..4)
+ # r.cover?(1) # => true
+ # r.cover?(4) # => true
+ # r.cover?(0) # => false
+ # r.cover?(5) # => false
+ # r.cover?('foo') # => false
+ #
+ # r = ('a'..'d')
+ # r.cover?('a') # => true
+ # r.cover?('d') # => true
+ # r.cover?(' ') # => false
+ # r.cover?('e') # => false
+ # r.cover?(0) # => false
+ #
+ # For range `r` with excluded end value (`#exclude_end? == true`), evaluates
+ # thus:
+ #
+ # r.begin <= object < r.end
+ #
+ # Examples:
+ #
+ # r = (1...4)
+ # r.cover?(1) # => true
+ # r.cover?(3) # => true
+ # r.cover?(0) # => false
+ # r.cover?(4) # => false
+ # r.cover?('foo') # => false
+ #
+ # r = ('a'...'d')
+ # r.cover?('a') # => true
+ # r.cover?('c') # => true
+ # r.cover?(' ') # => false
+ # r.cover?('d') # => false
+ # r.cover?(0) # => false
+ #
+ # With range argument `range`, compares the first and last elements of `self`
+ # and `range`:
+ #
+ # r = (1..4)
+ # r.cover?(1..4) # => true
+ # r.cover?(0..4) # => false
+ # r.cover?(1..5) # => false
+ # r.cover?('a'..'d') # => false
+ #
+ # r = (1...4)
+ # r.cover?(1..3) # => true
+ # r.cover?(1..4) # => false
+ #
+ # If begin and end are numeric, #cover? behaves like #include?
+ #
+ # (1..3).cover?(1.5) # => true
+ # (1..3).include?(1.5) # => true
+ #
+ # But when not numeric, the two methods may differ:
+ #
+ # ('a'..'d').cover?('cc') # => true
+ # ('a'..'d').include?('cc') # => false
+ #
+ # 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
+ # comparable.
+ #
+ #
+ # Related: Range#include?.
+ #
def cover?: (untyped obj) -> bool
+ # <!--
+ # rdoc-file=range.c
+ # - each {|element| ... } -> self
+ # - each -> an_enumerator
+ # -->
+ # With a block given, passes each element of `self` to the block:
+ #
+ # a = []
+ # (1..4).each {|element| a.push(element) } # => 1..4
+ # a # => [1, 2, 3, 4]
+ #
+ # Raises an exception unless `self.first.respond_to?(:succ)`.
+ #
+ # With no block given, returns an enumerator.
+ #
def each: () { (Elem arg0) -> untyped } -> self
| () -> ::Enumerator[Elem, self]
- # Returns the object that defines the end of the range.
+ # <!--
+ # rdoc-file=range.c
+ # - self.end -> object
+ # -->
+ # Returns the object that defines the end of `self`.
#
- # ```ruby
- # (1..10).end #=> 10
- # (1...10).end #=> 10
- # ```
- def `end`: () -> Elem # End-less ranges have type of Range[Integer?]
+ # (1..4).end # => 4
+ # (1...4).end # => 4
+ # (1..).end # => nil
+ #
+ # Related: Range#begin, Range#last.
+ #
+ def end: () -> Elem
- # Returns `true` if the range excludes its end value.
+ # <!--
+ # rdoc-file=range.c
+ # - exclude_end? -> true or false
+ # -->
+ # Returns `true` if `self` excludes its end value; `false` otherwise:
#
- # ```ruby
- # (1..5).exclude_end? #=> false
- # (1...5).exclude_end? #=> true
- # ```
- def `exclude_end?`: () -> bool
+ # Range.new(2, 5).exclude_end? # => false
+ # Range.new(2, 5, true).exclude_end? # => true
+ # (2..5).exclude_end? # => false
+ # (2...5).exclude_end? # => true
+ #
+ def exclude_end?: () -> bool
- # Returns the first object in the range, or an array of the first `n`
- # elements.
+ # <!--
+ # rdoc-file=range.c
+ # - first -> object
+ # - first(n) -> array
+ # -->
+ # With no argument, returns the first element of `self`, if it exists:
#
- # ```ruby
- # (10..20).first #=> 10
- # (10..20).first(3) #=> [10, 11, 12]
- # ```
+ # (1..4).first # => 1
+ # ('a'..'d').first # => "a"
+ #
+ # With non-negative integer argument `n` given, returns the first `n` elements
+ # in an array:
+ #
+ # (1..10).first(3) # => [1, 2, 3]
+ # (1..10).first(0) # => []
+ # (1..4).first(50) # => [1, 2, 3, 4]
+ #
+ # Raises an exception if there is no first element:
+ #
+ # (..4).first # Raises RangeError
+ #
def first: () -> Elem
| (Integer n) -> ::Array[Elem]
- # Compute a hash-code for this range. Two ranges with equal begin and end
- # points (using `eql?` ), and the same
- # [exclude\_end?](Range.downloaded.ruby_doc#method-i-exclude_end-3F) value
- # will generate the same hash-code.
+ # <!--
+ # rdoc-file=range.c
+ # - hash -> integer
+ # -->
+ # Returns the integer hash value for `self`. Two range objects `r0` and `r1`
+ # have the same hash value if and only if `r0.eql?(r1)`.
#
- # See also Object\#hash.
+ # Related: Range#eql?, Object#hash.
+ #
def hash: () -> Integer
- def `include?`: (untyped obj) -> bool
+ # <!-- rdoc-file=range.c -->
+ # Returns `true` if `object` is an element of `self`, `false` otherwise:
+ #
+ # (1..4).include?(2) # => true
+ # (1..4).include?(5) # => false
+ # (1..4).include?(4) # => true
+ # (1...4).include?(4) # => false
+ # ('a'..'d').include?('b') # => true
+ # ('a'..'d').include?('e') # => false
+ # ('a'..'d').include?('B') # => false
+ # ('a'..'d').include?('d') # => true
+ # ('a'...'d').include?('d') # => false
+ #
+ # If begin and end are numeric, #include? behaves like #cover?
+ #
+ # (1..3).include?(1.5) # => true
+ # (1..3).cover?(1.5) # => true
+ #
+ # But when not numeric, the two methods may differ:
+ #
+ # ('a'..'d').include?('cc') # => false
+ # ('a'..'d').cover?('cc') # => true
+ #
+ # Related: Range#cover?.
+ #
+ # Range#member? is an alias for Range#include?.
+ #
+ def include?: (untyped obj) -> bool
+ # <!--
+ # rdoc-file=range.c
+ # - Range.new(begin, end, exclude_end = false) -> new_range
+ # -->
+ # Returns a new range based on the given objects `begin` and `end`. Optional
+ # argument `exclude_end` determines whether object `end` is included as the last
+ # object in the range:
+ #
+ # Range.new(2, 5).to_a # => [2, 3, 4, 5]
+ # Range.new(2, 5, true).to_a # => [2, 3, 4]
+ # Range.new('a', 'd').to_a # => ["a", "b", "c", "d"]
+ # Range.new('a', 'd', true).to_a # => ["a", "b", "c"]
+ #
def initialize: (Elem from, Elem to, ?boolish exclude_end) -> void
- # Convert this range object to a printable form (using `inspect` to
- # convert the begin and end objects).
+ # <!--
+ # rdoc-file=range.c
+ # - inspect -> string
+ # -->
+ # Returns a string representation of `self`, including `begin.inspect` and
+ # `end.inspect`:
+ #
+ # (1..4).inspect # => "1..4"
+ # (1...4).inspect # => "1...4"
+ # (1..).inspect # => "1.."
+ # (..4).inspect # => "..4"
+ #
+ # Note that returns from #to_s and #inspect may differ:
+ #
+ # ('a'..'d').to_s # => "a..d"
+ # ('a'..'d').inspect # => "\"a\"..\"d\""
+ #
+ # Related: Range#to_s.
+ #
def inspect: () -> String
- # Returns the last object in the range, or an array of the last `n`
- # elements.
+ # <!--
+ # rdoc-file=range.c
+ # - last -> object
+ # - last(n) -> array
+ # -->
+ # With no argument, returns the last element of `self`, if it exists:
#
- # Note that with no arguments `last` will return the object that defines
- # the end of the range even if
- # [exclude\_end?](Range.downloaded.ruby_doc#method-i-exclude_end-3F) is
- # `true` .
+ # (1..4).last # => 4
+ # ('a'..'d').last # => "d"
#
- # ```ruby
- # (10..20).last #=> 20
- # (10...20).last #=> 20
- # (10..20).last(3) #=> [18, 19, 20]
- # (10...20).last(3) #=> [17, 18, 19]
- # ```
+ # Note that `last` with no argument returns the end element of `self` even if
+ # #exclude_end? is `true`:
+ #
+ # (1...4).last # => 4
+ # ('a'...'d').last # => "d"
+ #
+ # With non-negative integer argument `n` given, returns the last `n` elements in
+ # an array:
+ #
+ # (1..10).last(3) # => [8, 9, 10]
+ # (1..10).last(0) # => []
+ # (1..4).last(50) # => [1, 2, 3, 4]
+ #
+ # Note that `last` with argument does not return the end element of `self` if
+ # #exclude_end? it `true`:
+ #
+ # (1...4).last(3) # => [1, 2, 3]
+ # ('a'...'d').last(3) # => ["a", "b", "c"]
+ #
+ # Raises an exception if there is no last element:
+ #
+ # (1..).last # Raises RangeError
+ #
def last: () -> Elem
| (Integer n) -> ::Array[Elem]
- # Returns the maximum value in the range. Returns `nil` if the begin value
- # of the range larger than the end value. Returns `nil` if the begin value
- # of an exclusive range is equal to the end value.
+ # <!--
+ # rdoc-file=range.c
+ # - max -> object
+ # - max(n) -> array
+ # - max {|a, b| ... } -> object
+ # - max(n) {|a, b| ... } -> array
+ # -->
+ # Returns the maximum value in `self`, using method `<=>` or a given block for
+ # comparison.
#
- # Can be given an optional block to override the default comparison method
- # `a <=> b` .
+ # With no argument and no block given, returns the maximum-valued element of
+ # `self`.
#
- # ```ruby
- # (10..20).max #=> 20
- # ```
+ # (1..4).max # => 4
+ # ('a'..'d').max # => "d"
+ # (-4..-1).max # => -1
+ #
+ # With non-negative integer argument `n` given, and no block given, returns the
+ # `n` maximum-valued elements of `self` in an array:
+ #
+ # (1..4).max(2) # => [4, 3]
+ # ('a'..'d').max(2) # => ["d", "c"]
+ # (-4..-1).max(2) # => [-1, -2]
+ # (1..4).max(50) # => [4, 3, 2, 1]
+ #
+ # If a block is given, it is called:
+ #
+ # * First, with the first two element of `self`.
+ # * 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
+ #
+ # Output:
+ #
+ # [2, 1]
+ # [3, 2]
+ # [4, 3]
+ #
+ # With no argument and a block given, returns the return value of the last call
+ # to the block:
+ #
+ # (1..4).max {|a, b| -(a <=> b) } # => 1
+ #
+ # With non-negative integer argument `n` given, and a block given, returns the
+ # return values of the last `n` calls to the block in an array:
+ #
+ # (1..4).max(2) {|a, b| -(a <=> b) } # => [1, 2]
+ # (1..4).max(50) {|a, b| -(a <=> b) } # => [1, 2, 3, 4]
+ #
+ # Returns an empty array if `n` is zero:
+ #
+ # (1..4).max(0) # => []
+ # (1..4).max(0) {|a, b| -(a <=> b) } # => []
+ #
+ # Returns `nil` or an empty array if:
+ #
+ # * The begin value of the range is larger than the end value:
+ #
+ # (4..1).max # => nil
+ # (4..1).max(2) # => []
+ # (4..1).max {|a, b| -(a <=> b) } # => nil
+ # (4..1).max(2) {|a, b| -(a <=> b) } # => []
+ #
+ # * The begin value of an exclusive range is equal to the end value:
+ #
+ # (1...1).max # => nil
+ # (1...1).max(2) # => []
+ # (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
| () { (Elem a, Elem b) -> Integer } -> Elem
| (Integer n) -> ::Array[Elem]
| (Integer n) { (Elem a, Elem b) -> Integer } -> ::Array[Elem]
- # Returns the minimum value in the range. Returns `nil` if the begin value
- # of the range is larger than the end value. Returns `nil` if the begin
- # value of an exclusive range is equal to the end value.
+ # <!--
+ # rdoc-file=range.c
+ # - min -> object
+ # - min(n) -> array
+ # - min {|a, b| ... } -> object
+ # - min(n) {|a, b| ... } -> array
+ # -->
+ # Returns the minimum value in `self`, using method `<=>` or a given block for
+ # comparison.
#
- # Can be given an optional block to override the default comparison method
- # `a <=> b` .
+ # With no argument and no block given, returns the minimum-valued element of
+ # `self`.
#
- # ```ruby
- # (10..20).min #=> 10
- # ```
+ # (1..4).min # => 1
+ # ('a'..'d').min # => "a"
+ # (-4..-1).min # => -4
+ #
+ # With non-negative integer argument `n` given, and no block given, returns the
+ # `n` minimum-valued elements of `self` in an array:
+ #
+ # (1..4).min(2) # => [1, 2]
+ # ('a'..'d').min(2) # => ["a", "b"]
+ # (-4..-1).min(2) # => [-4, -3]
+ # (1..4).min(50) # => [1, 2, 3, 4]
+ #
+ # If a block is given, it is called:
+ #
+ # * First, with the first two element of `self`.
+ # * 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
+ #
+ # Output:
+ #
+ # [2, 1]
+ # [3, 1]
+ # [4, 1]
+ #
+ # With no argument and a block given, returns the return value of the last call
+ # to the block:
+ #
+ # (1..4).min {|a, b| -(a <=> b) } # => 4
+ #
+ # With non-negative integer argument `n` given, and a block given, returns the
+ # return values of the last `n` calls to the block in an array:
+ #
+ # (1..4).min(2) {|a, b| -(a <=> b) } # => [4, 3]
+ # (1..4).min(50) {|a, b| -(a <=> b) } # => [4, 3, 2, 1]
+ #
+ # Returns an empty array if `n` is zero:
+ #
+ # (1..4).min(0) # => []
+ # (1..4).min(0) {|a, b| -(a <=> b) } # => []
+ #
+ # Returns `nil` or an empty array if:
+ #
+ # * The begin value of the range is larger than the end value:
+ #
+ # (4..1).min # => nil
+ # (4..1).min(2) # => []
+ # (4..1).min {|a, b| -(a <=> b) } # => nil
+ # (4..1).min(2) {|a, b| -(a <=> b) } # => []
+ #
+ # * The begin value of an exclusive range is equal to the end value:
+ #
+ # (1...1).min # => nil
+ # (1...1).min(2) # => []
+ # (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
| () { (Elem a, Elem b) -> Integer } -> Elem
| (Integer n) -> ::Array[Elem]
| (Integer n) { (Elem a, Elem b) -> Integer } -> ::Array[Elem]
- # Returns the number of elements in the range. Both the begin and the end
- # of the [Range](Range.downloaded.ruby_doc) must be
- # [Numeric](https://ruby-doc.org/core-2.6.3/Numeric.html), otherwise nil
- # is returned.
+ # <!--
+ # rdoc-file=range.c
+ # - size -> non_negative_integer or Infinity or nil
+ # -->
+ # Returns the count of elements in `self` if both begin and end values are
+ # numeric; otherwise, returns `nil`:
#
- # ```ruby
- # (10..20).size #=> 11
- # ('a'..'z').size #=> nil
- # (-Float::INFINITY..Float::INFINITY).size #=> Infinity
- # ```
+ # (1..4).size # => 4
+ # (1...4).size # => 3
+ # (1..).size # => Infinity
+ # ('a'..'z').size #=> nil
+ #
+ # Related: Range#count.
+ #
def size: () -> Integer?
| () -> Float?
+ # <!--
+ # rdoc-file=range.c
+ # - step(n = 1) {|element| ... } -> self
+ # - step(n = 1) -> enumerator
+ # -->
+ # Iterates over the elements of `self`.
+ #
+ # With a block given and no argument, calls the block each element of the range;
+ # returns `self`:
+ #
+ # 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"]
+ #
+ # With a block given and a positive integer argument `n` given, calls the block
+ # with element `0`, element `n`, element `2n`, and so on:
+ #
+ # 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"]
+ #
+ # With no block given, returns an enumerator, which will be of class
+ # Enumerator::ArithmeticSequence if `self` is numeric; otherwise of class
+ # Enumerator:
+ #
+ # e = (1..5).step(2) # => ((1..5).step(2))
+ # e.class # => Enumerator::ArithmeticSequence
+ # ('a'..'e').step # => #<Enumerator: ...>
+ #
+ # Related: Range#%.
+ #
def step: (?Integer n) { (Elem arg0) -> untyped } -> self
| (?Integer n) -> ::Enumerator[Elem, void]
- # Convert this range object to a printable form (using
- # [to\_s](Range.downloaded.ruby_doc#method-i-to_s) to convert the begin
- # and end objects).
+ # <!--
+ # rdoc-file=range.c
+ # - to_s -> string
+ # -->
+ # Returns a string representation of `self`, including `begin.to_s` and
+ # `end.to_s`:
+ #
+ # (1..4).to_s # => "1..4"
+ # (1...4).to_s # => "1...4"
+ # (1..).to_s # => "1.."
+ # (..4).to_s # => "..4"
+ #
+ # Note that returns from #to_s and #inspect may differ:
+ #
+ # ('a'..'d').to_s # => "a..d"
+ # ('a'..'d').inspect # => "\"a\"..\"d\""
+ #
+ # Related: Range#inspect.
+ #
def to_s: () -> String
+ # <!--
+ # rdoc-file=range.c
+ # - eql?(other) -> true or false
+ # -->
+ # Returns `true` if and only if:
+ #
+ # * `other` is a range.
+ # * `other.begin eql? self.begin`.
+ # * `other.end eql? self.end`.
+ # * `other.exclude_end? == self.exclude_end?`.
+ #
+ #
+ # Otherwise returns `false`.
+ #
+ # r = (1..5)
+ # r.eql?(1..5) # => true
+ # r = Range.new(1, 5)
+ # r.eql?('foo') # => false
+ # r.eql?(2..5) # => false
+ # r.eql?(1..4) # => false
+ # r.eql?(1...5) # => false
+ # r.eql?(Range.new(1, 5, true)) # => false
+ #
+ # Note that even with the same argument, the return values of #== and #eql? can
+ # differ:
+ #
+ # (1..2) == (1..2.0) # => true
+ # (1..2).eql? (1..2.0) # => false
+ #
+ # Related: Range#==.
+ #
def eql?: (untyped obj) -> bool
+ # <!--
+ # rdoc-file=range.c
+ # - include?(object) -> true or false
+ # -->
+ # Returns `true` if `object` is an element of `self`, `false` otherwise:
+ #
+ # (1..4).include?(2) # => true
+ # (1..4).include?(5) # => false
+ # (1..4).include?(4) # => true
+ # (1...4).include?(4) # => false
+ # ('a'..'d').include?('b') # => true
+ # ('a'..'d').include?('e') # => false
+ # ('a'..'d').include?('B') # => false
+ # ('a'..'d').include?('d') # => true
+ # ('a'...'d').include?('d') # => false
+ #
+ # If begin and end are numeric, #include? behaves like #cover?
+ #
+ # (1..3).include?(1.5) # => true
+ # (1..3).cover?(1.5) # => true
+ #
+ # But when not numeric, the two methods may differ:
+ #
+ # ('a'..'d').include?('cc') # => false
+ # ('a'..'d').cover?('cc') # => true
+ #
+ # Related: Range#cover?.
+ #
+ # Range#member? is an alias for Range#include?.
+ #
def member?: (untyped obj) -> bool
end