Merge pull request #2562 from ksss/range

Add documentation for `Range#{minmax,count,to_a,entries}`

Author: ksss

core/range.rbs

@@ -825,6 +825,51 @@ class Range[out Elem] < Object
   #
   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 `#<=>` or a given block.
+  #
+  # With no block given, returns the minimum and maximum values, using `#<=>` 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 `self.size` 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 `[nil, nil]` 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
   #   - overlap?(range) -> true or false
@@ -932,6 +977,42 @@ class Range[out Elem] < Object
   #
   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
   #   - step(s = 1) {|element| ... } -> self
@@ -1097,4 +1178,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

test/stdlib/Range_test.rb

@@ -156,4 +156,22 @@ def test_max
     assert_send_type "(::Integer) -> ::Array[::Integer]", (1..4), :max, 2
     assert_send_type "(::Integer) { (::Integer, ::Integer) -> ::Integer } -> ::Array[::Integer]", (4..1), :max, 0 do |a, b| a <=> b end
   end
+
+  def test_minmax
+    assert_send_type "() -> [::Integer, ::Integer]", (1..4), :minmax
+    assert_send_type "() -> [nil, nil]", [], :minmax
+    assert_send_type "() { (::Integer, ::Integer) -> ::Integer } -> [::Integer, ::Integer]", (1..4), :minmax do |a, b| a.size <=> b.size end
+    assert_send_type "() { (::Integer, ::Integer) -> ::Integer } -> [nil, nil]", [], :minmax do |a, b| a <=> b end
+  end
+
+  def test_count
+    assert_send_type "() -> ::Integer", (1..4), :count
+    assert_send_type "() -> ::Float", (1..), :count
+    assert_send_type "(::Integer) -> ::Integer", (1..4), :count, 2
+    assert_send_type "() { (::Integer) -> boolish } -> ::Integer", (1..4), :count do |element| element < 3 end
+  end
+
+  def test_to_a
+    assert_send_type "() -> ::Array[::Integer]", (1..4), :to_a
+  end
 end