core/range.rbs in rbs-3.0.0.dev.2 vs core/range.rbs in rbs-3.0.0.dev.3

- old
+ new

@@ -2,11 +2,11 @@ # A Range object represents a collection of values that are between given begin # and end values. # # 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] # ('a'..'d').to_a # => ["a", "b", "c", "d"] # # Ranges that use '...' to exclude the given end value. @@ -56,13 +56,13 @@ # r.end # => nil # r.include?(50) # => 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: +# 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 @@ -82,10 +82,19 @@ # a.push(i) if i.even? # break if i > 10 # 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. @@ -116,13 +125,12 @@ # 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. +# `<=>`; 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 # construct ranges and to iterate over them. Note that the Comparable module is # included so the `==` method is defined in terms of `<=>`. # @@ -154,118 +162,71 @@ # # ## 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 +# * 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 Creating a Range # -# ::new -# : Returns a new range. +# * ::new: Returns a new range. # # -# # ### Methods for Querying # -# #begin -# : Returns the begin value given for `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`. # -# #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 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 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`. +# * #%: 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`. # -# #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). +# * #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). # -# #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 @@ -442,9 +403,50 @@ # # * The begin value of `self` is larger than its end value. # * 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?. # def cover?: (untyped obj) -> bool