Merge pull request #2767 from ruby/ruby-module

Add `Ruby`, `Array#find`, and `Array#rfind`

Author: soutaro

core/array.rbs

@@ -2019,6 +2019,32 @@ class Array[unchecked out Elem] < Object
   def filter!: () { (Elem item) -> boolish } -> self?
              | () -> ::Enumerator[Elem, self?]
 
+  # <!--
+  #   rdoc-file=array.c
+  #   - find(if_none_proc = nil) {|element| ... } -> object or nil
+  #   - find(if_none_proc = nil) -> enumerator
+  # -->
+  # Returns the first element for which the block returns a truthy value.
+  #
+  # With a block given, calls the block with successive elements of the array;
+  # returns the first element for which the block returns a truthy value:
+  #
+  #     (0..9).find {|element| element > 2}                # => 3
+  #
+  # If no such element is found, calls `if_none_proc` and returns its return
+  # value.
+  #
+  #     (0..9).find(proc {false}) {|element| element > 12} # => false
+  #     {foo: 0, bar: 1, baz: 2}.find {|key, value| key.start_with?('b') }            # => [:bar, 1]
+  #     {foo: 0, bar: 1, baz: 2}.find(proc {[]}) {|key, value| key.start_with?('c') } # => []
+  #
+  # With no block given, returns an Enumerator.
+  #
+  def find: () { (Elem) -> boolish } -> Elem?
+          | () -> ::Enumerator[Elem, Elem?]
+          | [T] (Enumerable::_NotFound[T] ifnone) { (Elem) -> boolish } -> (Elem | T)
+          | [T] (Enumerable::_NotFound[T] ifnone) -> ::Enumerator[Elem, Elem | T]
+
   # <!--
   #   rdoc-file=array.c
   #   - find_index(object) -> integer or nil
@@ -2988,6 +3014,33 @@ class Array[unchecked out Elem] < Object
   def reverse_each: () { (Elem item) -> void } -> self
                   | () -> ::Enumerator[Elem, self]
 
+  # <!--
+  #   rdoc-file=array.c
+  #   - rfind(if_none_proc = nil) {|element| ... } -> object or nil
+  #   - rfind(if_none_proc = nil) -> enumerator
+  # -->
+  # Returns the last element for which the block returns a truthy value.
+  #
+  # With a block given, calls the block with successive elements of the array in
+  # reverse order; returns the last element for which the block returns a truthy
+  # value:
+  #
+  #     (0..9).rfind {|element| element < 5}                # => 4
+  #
+  # If no such element is found, calls `if_none_proc` and returns its return
+  # value.
+  #
+  #     (0..9).rfind(proc {false}) {|element| element < -2} # => false
+  #     {foo: 0, bar: 1, baz: 2}.rfind {|key, value| key.start_with?('b') }            # => [:baz, 2]
+  #     {foo: 0, bar: 1, baz: 2}.rfind(proc {[]}) {|key, value| key.start_with?('c') } # => []
+  #
+  # With no block given, returns an Enumerator.
+  #
+  def rfind: () { (Elem) -> boolish } -> Elem?
+           | () -> ::Enumerator[Elem, Elem?]
+           | [T] (Enumerable::_NotFound[T] ifnone) { (Elem) -> boolish } -> (Elem | T)
+           | [T] (Enumerable::_NotFound[T] ifnone) -> ::Enumerator[Elem, Elem | T]
+
   # <!--
   #   rdoc-file=array.c
   #   - rindex(object) -> integer or nil

core/ruby.rbs

@@ -0,0 +1,53 @@
+# <!-- rdoc-file=version.c -->
+# The [Ruby](rdoc-ref:Ruby) module that contains portable information among
+# implementations.
+#
+# The constants defined here are aliased in the toplevel with `RUBY_` prefix.
+#
+module Ruby
+  # <!-- rdoc-file=version.c -->
+  # The copyright string for ruby
+  #
+  COPYRIGHT: ::String
+
+  # <!-- rdoc-file=version.c -->
+  # The full ruby version string, like `ruby -v` prints
+  #
+  DESCRIPTION: ::String
+
+  # <!-- rdoc-file=version.c -->
+  # The engine or interpreter this ruby uses.
+  #
+  ENGINE: ::String
+
+  # <!-- rdoc-file=version.c -->
+  # The version of the engine or interpreter this ruby uses.
+  #
+  ENGINE_VERSION: ::String
+
+  # <!-- rdoc-file=version.c -->
+  # The patchlevel for this ruby.  If this is a development build of ruby the
+  # patchlevel will be -1
+  #
+  PATCHLEVEL: ::Integer
+
+  # <!-- rdoc-file=version.c -->
+  # The platform for this ruby
+  #
+  PLATFORM: ::String
+
+  # <!-- rdoc-file=version.c -->
+  # The date this ruby was released
+  #
+  RELEASE_DATE: ::String
+
+  # <!-- rdoc-file=version.c -->
+  # The GIT commit hash for this ruby.
+  #
+  REVISION: ::String
+
+  # <!-- rdoc-file=version.c -->
+  # The running version of ruby
+  #
+  VERSION: ::String
+end

test/stdlib/Array_test.rb

@@ -411,6 +411,20 @@ def test_filter!
                      [1,2,3], :filter!
   end
 
+  def test_find
+    assert_send_type "() { (Integer) -> bool } -> Integer",
+                     [1,2,3], :find, &->(i) { i.odd? }
+    assert_send_type "() { (Integer) -> bool } -> nil",
+                     [0,2], :find, &->(i) { i.odd? }
+    assert_send_type "(Enumerable::_NotFound[String]) { (Integer) -> bool } -> String",
+                     [0,2], :find, -> { "" }, &->(i) { i.odd? }
+
+    assert_send_type "() -> Enumerator[Integer, Integer?]",
+                     [1,2,3], :find
+    assert_send_type "(Enumerable::_NotFound[String]) -> Enumerator[Integer, Integer | String | nil]",
+                     [0,2], :find, -> { "" }
+  end
+
   def test_find_index
     assert_send_type "(Integer) -> Integer",
                      [1,2,3], :find_index, 1
@@ -724,6 +738,20 @@ def test_reverse_each
                      [2,3,4], :reverse_each
   end
 
+  def test_rfind
+    assert_send_type "() { (Integer) -> bool } -> Integer",
+                     [1,2,3], :rfind, &->(i) { i.odd? }
+    assert_send_type "() { (Integer) -> bool } -> nil",
+                     [0,2], :rfind, &->(i) { i.odd? }
+    assert_send_type "(Enumerable::_NotFound[String]) { (Integer) -> bool } -> String",
+                     [0,2], :rfind, -> { "" }, &->(i) { i.odd? }
+
+    assert_send_type "() -> Enumerator[Integer, Integer?]",
+                     [1,2,3], :rfind
+    assert_send_type "(Enumerable::_NotFound[String]) -> Enumerator[Integer, Integer | String | nil]",
+                     [0,2], :rfind, -> { "" }
+  end
+
   def test_rindex
     assert_send_type "(Integer) -> Integer",
                      [1,2,3], :rindex, 1

test/stdlib/Ruby_test.rb

@@ -0,0 +1,20 @@
+require_relative "test_helper"
+require "resolv"
+
+class RubyTest < Test::Unit::TestCase
+  include TestHelper
+
+  testing "::Ruby"
+
+  def test_constants
+    assert_const_type '::String', 'Ruby::COPYRIGHT'
+    assert_const_type '::String', 'Ruby::DESCRIPTION'
+    assert_const_type '::String', 'Ruby::ENGINE'
+    assert_const_type '::String', 'Ruby::ENGINE_VERSION'
+    assert_const_type '::Integer', 'Ruby::PATCHLEVEL'
+    assert_const_type '::String', 'Ruby::PLATFORM'
+    assert_const_type '::String', 'Ruby::RELEASE_DATE'
+    assert_const_type '::String', 'Ruby::REVISION'
+    assert_const_type '::String', 'Ruby::VERSION'
+  end
+end