rbs 4.0.0.dev.4 → 4.0.0

data/core/random.rbs

@@ -96,6 +96,23 @@ class Random < RBS::Unnamed::Random_Base
                | (Float | ::Range[Float] max) -> Float
                | [T < Numeric] (::Range[T]) -> T
 
+  # <!--
+  #   rdoc-file=random.c
+  #   - Random.seed -> integer
+  # -->
+  # Returns the seed value used to initialize the Ruby system PRNG. This may be
+  # used to initialize another generator with the same state at a later time,
+  # causing it to produce the same sequence of numbers.
+  #
+  #     Random.seed      #=> 1234
+  #     prng1 = Random.new(Random.seed)
+  #     prng1.seed       #=> 1234
+  #     prng1.rand(100)  #=> 47
+  #     Random.seed      #=> 1234
+  #     Random.rand(100) #=> 47
+  #
+  def self.seed: () -> ::Integer
+
   # <!--
   #   rdoc-file=random.c
   #   - srand(number = Random.new_seed) -> old_seed
@@ -173,9 +190,10 @@ end
 # <!-- rdoc-file=lib/random/formatter.rb -->
 # ## Random number formatter.
 #
-# Formats generated random numbers in many manners. When `'random/formatter'` is
-# required, several methods are added to empty core module `Random::Formatter`,
-# making them available as Random's instance and module methods.
+# Formats generated random numbers in many manners. When
+# <code>'random/formatter'</code> is required, several methods are added to
+# empty core module <code>Random::Formatter</code>, making them available as
+# Random's instance and module methods.
 #
 # Standard library SecureRandom is also extended with the module, and the
 # methods described below are available as a module methods in it.

data/core/range.rbs

@@ -86,20 +86,21 @@
 #     end
 #     a # => [2, 4, 6, 8, 10]
 #
-# A range can be both beginless and endless.  For literal beginless, endless
+# 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:
+# end, since that is what Ruby uses for Range#inspect:
 #
-#     (nil..)    # => (nil..)
-#     (..nil)    # => (nil..)
-#     (nil..nil) # => (nil..)
+#     (nil..)    # => (nil..nil)
+#     (..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.
+# <code>#<=></code>. Ruby core classes that do so include Array, Complex,
+# File::Stat, Float, Integer, Kernel, Module, Numeric, Rational, String, Symbol,
+# and Time.
 #
 # Example:
 #
@@ -128,12 +129,13 @@
 # ## Ranges and User-Defined Classes
 #
 # A user-defined class that is to be used in a range must implement instance
-# method `#<=>`; see Integer#<=>. To make iteration available, it must also
-# implement instance method `succ`; see Integer#succ.
+# method <code>#<=></code>; 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 `#<=>`.
+# The class below implements both <code>#<=></code> 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 <code>==</code> method is defined in
+# terms of <code>#<=></code>.
 #
 #     # Represent a string of 'X' characters.
 #     class Xs
@@ -268,9 +270,9 @@ class Range[out Elem] < Object
   # Returns `true` if and only if:
   #
   # *   `other` is a range.
-  # *   `other.begin == self.begin`.
-  # *   `other.end == self.end`.
-  # *   `other.exclude_end? == self.exclude_end?`.
+  # *   <code>other.begin == self.begin</code>.
+  # *   <code>other.end == self.end</code>.
+  # *   <code>other.exclude_end? == self.exclude_end?</code>.
   #
   # Otherwise returns `false`.
   #
@@ -297,8 +299,8 @@ class Range[out Elem] < Object
   #   rdoc-file=range.c
   #   - self === object ->  true or false
   # -->
-  # Returns `true` if `object` is between `self.begin` and `self.end`. `false`
-  # otherwise:
+  # Returns `true` if `object` is between <code>self.begin</code> and
+  # <code>self.end</code>. `false` otherwise:
   #
   #     (1..4) === 2       # => true
   #     (1..4) === 5       # => false
@@ -308,7 +310,7 @@ class Range[out Elem] < Object
   #     ('a'..'d') === 'c' # => true
   #     ('a'..'d') === 'e' # => false
   #
-  # A case statement uses method `===`, and so:
+  # A case statement uses method <code>===</code>, and so:
   #
   #     case 79
   #     when (1..50)
@@ -351,7 +353,7 @@ class Range[out Elem] < Object
   # -->
   # Returns an element from `self` selected by a binary search.
   #
-  # See [Binary Searching](rdoc-ref:bsearch.rdoc).
+  # See [Binary Searching](rdoc-ref:language/bsearch.rdoc).
   #
   def bsearch: () -> ::Enumerator[Elem, Elem?]
              | () { (Elem) -> (true | false) } -> Elem?
@@ -364,10 +366,11 @@ class Range[out Elem] < Object
   # -->
   # Returns `true` if the given argument is within `self`, `false` otherwise.
   #
-  # With non-range argument `object`, evaluates with `<=` and `<`.
+  # With non-range argument `object`, evaluates with <code><=</code> and
+  # <code><</code>.
   #
-  # For range `self` with included end value (`#exclude_end? == false`), evaluates
-  # thus:
+  # For range `self` with included end value (<code>#exclude_end? ==
+  # false</code>), evaluates thus:
   #
   #     self.begin <= object <= self.end
   #
@@ -387,8 +390,8 @@ class Range[out Elem] < Object
   #     r.cover?('e')     # => false
   #     r.cover?(0)       # => false
   #
-  # For range `r` with excluded end value (`#exclude_end? == true`), evaluates
-  # thus:
+  # For range `r` with excluded end value (<code>#exclude_end? == true</code>),
+  # evaluates thus:
   #
   #     r.begin <= object < r.end
   #
@@ -434,8 +437,8 @@ 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
-  #     comparable.
+  # *   An internal call to <code>#<=></code> 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
@@ -493,7 +496,7 @@ class Range[out Elem] < Object
   #     (1..4).each {|element| a.push(element) } # => 1..4
   #     a # => [1, 2, 3, 4]
   #
-  # Raises an exception unless `self.first.respond_to?(:succ)`.
+  # Raises an exception unless <code>self.first.respond_to?(:succ)</code>.
   #
   # With no block given, returns an enumerator.
   #
@@ -556,7 +559,7 @@ class Range[out Elem] < Object
   #   - 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)`.
+  # have the same hash value if and only if <code>r0.eql?(r1)</code>.
   #
   # Related: Range#eql?, Object#hash.
   #
@@ -608,8 +611,8 @@ class Range[out Elem] < Object
   #   rdoc-file=range.c
   #   - inspect -> string
   # -->
-  # Returns a string representation of `self`, including `begin.inspect` and
-  # `end.inspect`:
+  # Returns a string representation of `self`, including
+  # <code>begin.inspect</code> and <code>end.inspect</code>:
   #
   #     (1..4).inspect  # => "1..4"
   #     (1...4).inspect # => "1...4"
@@ -668,8 +671,8 @@ 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
-  # comparison.
+  # Returns the maximum value in `self`, using method <code>#<=></code> or a given
+  # block for comparison.
   #
   # With no argument and no block given, returns the maximum-valued element of
   # `self`.
@@ -736,15 +739,12 @@ class Range[out Elem] < Object
   #
   # Raises an exception if either:
   #
-  # *   `self` is a endless range: `(1..)`.
+  # *   `self` is a endless range: <code>(1..)</code>.
   # *   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]
+  def max: ...
 
   # <!--
   #   rdoc-file=range.c
@@ -753,8 +753,8 @@ 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
-  # comparison.
+  # Returns the minimum value in `self`, using method <code>#<=></code> or a given
+  # block for comparison.
   #
   # With no argument and no block given, returns the minimum-valued element of
   # `self`.
@@ -821,15 +821,58 @@ class Range[out Elem] < Object
   #
   # Raises an exception if either:
   #
-  # *   `self` is a beginless range: `(..4)`.
+  # *   `self` is a beginless range: <code>(..4)</code>.
   # *   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]
+  def min: ...
+
+  # <!--
+  #   rdoc-file=range.c
+  #   - minmax -> [object, object]
+  #   - minmax {|a, b| ... } -> [object, object]
+  # -->
+  # Returns a 2-element array containing the minimum and maximum value in `self`,
+  # either according to comparison method <code>#<=></code> or a given block.
+  #
+  # With no block given, returns the minimum and maximum values, using
+  # <code>#<=></code> for comparison:
+  #
+  #     (1..4).minmax     # => [1, 4]
+  #     (1...4).minmax    # => [1, 3]
+  #     ('a'..'d').minmax # => ["a", "d"]
+  #     (-4..-1).minmax   # => [-4, -1]
+  #
+  # With a block given, the block must return an integer:
+  #
+  # *   Negative if `a` is smaller than `b`.
+  # *   Zero if `a` and `b` are equal.
+  # *   Positive if `a` is larger than `b`.
+  #
+  # The block is called <code>self.size</code> times to compare elements; returns
+  # a 2-element Array containing the minimum and maximum values from `self`, per
+  # the block:
+  #
+  #     (1..4).minmax {|a, b| -(a <=> b) } # => [4, 1]
+  #
+  # Returns <code>[nil, nil]</code> if:
+  #
+  # *   The begin value of the range is larger than the end value:
+  #
+  #         (4..1).minmax                      # => [nil, nil]
+  #         (4..1).minmax {|a, b| -(a <=> b) } # => [nil, nil]
+  #
+  # *   The begin value of an exclusive range is equal to the end value:
+  #
+  #         (1...1).minmax                          # => [nil, nil]
+  #         (1...1).minmax  {|a, b| -(a <=> b) }    # => [nil, nil]
+  #
+  # Raises an exception if `self` is a beginless or an endless range.
+  #
+  # Related: Range#min, Range#max.
+  #
+  def minmax: ...
 
   # <!--
   #   rdoc-file=range.c
@@ -845,8 +888,8 @@ class Range[out Elem] < Object
   #
   #     (1..3).overlap?(1)         # TypeError
   #
-  # Returns `false` if an internal call to `#<=>` returns `nil`; that is, the
-  # operands are not comparable.
+  # Returns `false` if an internal call to <code>#<=></code> returns `nil`; that
+  # is, the operands are not comparable.
   #
   #     (1..3).overlap?('a'..'d')  # => false
   #
@@ -890,7 +933,8 @@ class Range[out Elem] < Object
   #     (...[]).overlap?(...[]) # => true
   #
   # Even if those ranges are effectively empty (no number can be smaller than
-  # `-Float::INFINITY`), they are still considered overlapping with themselves.
+  # <code>-Float::INFINITY</code>), they are still considered overlapping with
+  # themselves.
   #
   # Related: Range#cover?.
   #
@@ -936,8 +980,43 @@ class Range[out Elem] < Object
   #
   # Related: Range#count.
   #
-  def size: () -> Integer?
-          | () -> Float?
+  def size: () -> (Integer | Float | nil)
+
+  # <!--
+  #   rdoc-file=range.c
+  #   - count -> integer
+  #   - count(object) -> integer
+  #   - count {|element| ... } -> integer
+  # -->
+  # Returns the count of elements, based on an argument or block criterion, if
+  # given.
+  #
+  # With no argument and no block given, returns the number of elements:
+  #
+  #     (1..4).count      # => 4
+  #     (1...4).count     # => 3
+  #     ('a'..'d').count  # => 4
+  #     ('a'...'d').count # => 3
+  #     (1..).count       # => Infinity
+  #     (..4).count       # => Infinity
+  #
+  # With argument `object`, returns the number of `object` found in `self`, which
+  # will usually be zero or one:
+  #
+  #     (1..4).count(2)   # => 1
+  #     (1..4).count(5)   # => 0
+  #     (1..4).count('a')  # => 0
+  #
+  # With a block given, calls the block with each element; returns the number of
+  # elements for which the block returns a truthy value:
+  #
+  #     (1..4).count {|element| element < 3 } # => 2
+  #
+  # Related: Range#size.
+  #
+  def count: () -> (Integer | Float)
+           | (untyped) -> Integer
+           | () { (Elem) -> boolish } -> Integer
 
   # <!--
   #   rdoc-file=range.c
@@ -945,7 +1024,7 @@ class Range[out Elem] < Object
   #   - step(s = 1)                  -> enumerator/arithmetic_sequence
   # -->
   # Iterates over the elements of range in steps of `s`. The iteration is
-  # performed by `+` operator:
+  # performed by <code>+</code> operator:
   #
   #     (0..6).step(2) { puts _1 } #=> 1..5
   #     # Prints: 0, 2, 4, 6
@@ -960,8 +1039,8 @@ class Range[out Elem] < Object
   #     #   2022-02-28 00:00:00 UTC
   #     #   2022-03-01 00:00:00 UTC
   #
-  # If ` + step` decreases the value, iteration is still performed when step
-  # `begin` is higher than the `end`:
+  # If <code> + step</code> decreases the value, iteration is still performed when
+  # step `begin` is higher than the `end`:
   #
   #     (0..6).step(-2) { puts _1 }
   #     # Prints nothing
@@ -1026,8 +1105,8 @@ class Range[out Elem] < Object
   #   rdoc-file=range.c
   #   - to_s -> string
   # -->
-  # Returns a string representation of `self`, including `begin.to_s` and
-  # `end.to_s`:
+  # Returns a string representation of `self`, including <code>begin.to_s</code>
+  # and <code>end.to_s</code>:
   #
   #     (1..4).to_s  # => "1..4"
   #     (1...4).to_s # => "1...4"
@@ -1050,9 +1129,9 @@ 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.exclude_end? == self.exclude_end?`.
+  # *   <code>other.begin.eql?(self.begin)</code>.
+  # *   <code>other.end.eql?(self.end)</code>.
+  # *   <code>other.exclude_end? == self.exclude_end?</code>.
   #
   # Otherwise returns `false`.
   #
@@ -1104,4 +1183,27 @@ class Range[out Elem] < Object
   # Related: Range#cover?.
   #
   def member?: (untyped obj) -> bool
+
+  # <!--
+  #   rdoc-file=range.c
+  #   - to_a -> array
+  # -->
+  # Returns an array containing the elements in `self`, if a finite collection;
+  # raises an exception otherwise.
+  #
+  #     (1..4).to_a     # => [1, 2, 3, 4]
+  #     (1...4).to_a    # => [1, 2, 3]
+  #     ('a'..'d').to_a # => ["a", "b", "c", "d"]
+  #
+  def to_a: ...
+
+  # <!-- rdoc-file=range.c -->
+  # Returns an array containing the elements in `self`, if a finite collection;
+  # raises an exception otherwise.
+  #
+  #     (1..4).to_a     # => [1, 2, 3, 4]
+  #     (1...4).to_a    # => [1, 2, 3]
+  #     ('a'..'d').to_a # => ["a", "b", "c", "d"]
+  #
+  alias entries to_a
 end