Merge pull request #2189 from ruby/3.4-changes

Update type definitions for Ruby 3.4

Author: soutaro

core/array.rbs

@@ -1763,6 +1763,43 @@ class Array[unchecked out Elem] < Object
            | [T] (int index, T default) -> (Elem | T)
            | [T] (int index) { (int index) -> T } -> (Elem | T)
 
+  # <!--
+  #   rdoc-file=array.rb
+  #   - fetch_values(*indexes) -> new_array
+  #   - fetch_values(*indexes) {|index| ... } -> new_array
+  # -->
+  # With no block given, returns a new array containing the elements of `self` at
+  # the offsets given by `indexes`; each of the `indexes` must be an
+  # [integer-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects):
+  #
+  #     a = [:foo, :bar, :baz]
+  #     a.fetch_values(3, 1)   # => [:baz, :foo]
+  #     a.fetch_values(3.1, 1) # => [:baz, :foo]
+  #     a.fetch_values         # => []
+  #
+  # For a negative index, counts backwards from the end of the array:
+  #
+  #     a.fetch_values([-2, -1]) # [:bar, :baz]
+  #
+  # When no block is given, raises an exception if any index is out of range.
+  #
+  # With a block given, for each index:
+  #
+  # *   If the index in in range, uses an element of `self` (as above).
+  # *   Otherwise calls, the block with the index, and uses the block's return
+  #     value.
+  #
+  # Example:
+  #
+  #     a = [:foo, :bar, :baz]
+  #     a.fetch_values(1, 0, 42, 777) {|index| index.to_s}
+  #     # => [:bar, :foo, "42", "777"]
+  #
+  # Related: see [Methods for Fetching](rdoc-ref:Array@Methods+for+Fetching).
+  #
+  def fetch_values: (*int indexes) -> self
+
   # <!--
   #   rdoc-file=array.c
   #   - fill(object, start = nil, count = nil) -> new_array

core/exception.rbs

@@ -306,7 +306,8 @@ class Exception
   #
   # See [Backtraces](rdoc-ref:exceptions.md@Backtraces).
   #
-  def set_backtrace: (String | Array[String] backtrace) -> Array[String]
+  def set_backtrace: (String | Array[String]) -> Array[String]
+                   | (Array[Thread::Backtrace::Location]) -> Array[Thread::Backtrace::Location]
                    | (nil) -> nil
 
   # <!--

core/fiber.rbs

@@ -415,7 +415,7 @@ class Fiber < Object
   # See Kernel#raise for more information.
   #
   def raise: (?string msg) -> untyped
-           | (_Exception, ?string msg, ?Array[string] backtrace) -> untyped
+           | (_Exception, ?string msg, ?Array[string] | Array[Thread::Backtrace::Location] | nil backtrace) -> untyped
 
   # <!--
   #   rdoc-file=cont.c

core/gc.rbs

@@ -157,6 +157,61 @@ module GC
   #
   OPTS: Array[String]
 
+  # <!--
+  #   rdoc-file=gc.rb
+  #   - GC.config -> hash
+  #   - GC.config(hash) -> hash
+  # -->
+  # Sets or gets information about the current GC config.
+  #
+  # Configuration parameters are GC implementation-specific and may change without
+  # notice.
+  #
+  # This method can be called without parameters to retrieve the current config.
+  #
+  # This method can also be called with a `Hash` argument to assign values to
+  # valid config keys. Config keys missing from the passed `Hash` will be left
+  # unmodified.
+  #
+  # If a key/value pair is passed to this function that does not correspond to a
+  # valid config key for the GC implementation being used, no config will be
+  # updated, the key will be present in the returned Hash, and its value will be
+  # `nil`. This is to facilitate easy migration between GC implementations.
+  #
+  # In both call-seqs, the return value of `GC.config` will be a `Hash` containing
+  # the most recent full configuration, i.e., all keys and values defined by the
+  # specific GC implementation being used. In the case of a config update, the
+  # return value will include the new values being updated.
+  #
+  # This method is only expected to work on CRuby.
+  #
+  # Valid config keys for Ruby's default GC implementation are:
+  #
+  # rgengc_allow_full_mark
+  # :   Controls whether the GC is allowed to run a full mark (young & old
+  #     objects).
+  #
+  #     When `true`, GC interleaves major and minor collections. This is the
+  #     default. GC will function as intended.
+  #
+  #     When `false`, the GC will never trigger a full marking cycle unless
+  #     explicitly requested by user code. Instead, only a minor mark will
+  #     run—only young objects will be marked. When the heap space is exhausted,
+  #     new pages will be allocated immediately instead of running a full mark.
+  #
+  #     A flag will be set to notify that a full mark has been requested. This
+  #     flag is accessible using `GC.latest_gc_info(:needs_major_by)`
+  #
+  #     The user can trigger a major collection at any time using
+  #     `GC.start(full_mark: true)`
+  #
+  #     When `false`, Young to Old object promotion is disabled. For performance
+  #     reasons, it is recommended to warm up an application using
+  #     `Process.warmup` before setting this parameter to `false`.
+  #
+  def self.config: () -> Hash[Symbol, untyped]
+                 | (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
   # <!--
   #   rdoc-file=gc.rb
   #   - GC.count -> Integer

core/hash.rbs

@@ -1844,9 +1844,9 @@ class Hash[unchecked out K, unchecked out V] < Object
   # allocated with enough capacity to accommodate this many keys without having to
   # be resized.
   #
-  def initialize: () -> void
-                | (untyped default) -> void
-                | [A, B] () { (Hash[A, B] hash, A key) -> B } -> void
+  def initialize: (?capacity: int) -> void
+                | [V] (V default, ?capacity: int) -> void
+                | [A, B] (?capacity: int) { (Hash[A, B] hash, A key) -> B } -> void
 
   # <!--
   #   rdoc-file=hash.c

core/kernel.rbs

@@ -983,7 +983,7 @@ module Kernel : BasicObject
   #
   def self?.fail: () -> bot
                 | (string message, ?cause: Exception?) -> bot
-                | (_Exception exception, ?_ToS? message, ?String | Array[String] | nil backtrace, ?cause: Exception?) -> bot
+                | (_Exception exception, ?_ToS? message, ?String | Array[String] | Array[Thread::Backtrace::Location] | nil backtrace, ?cause: Exception?) -> bot
                 | (_Exception exception, ?cause: Exception?, **untyped) -> bot
 
   # <!--

core/match_data.rbs

@@ -132,6 +132,82 @@ class MatchData
   #
   def begin: (capture backref) -> Integer?
 
+  # <!--
+  #   rdoc-file=re.c
+  #   - bytebegin(n) -> integer
+  #   - bytebegin(name) -> integer
+  # -->
+  # Returns the offset (in bytes) of the beginning of the specified match.
+  #
+  # When non-negative integer argument `n` is given, returns the offset of the
+  # beginning of the `n`th match:
+  #
+  #     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
+  #     # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
+  #     m[0]       # => "HX1138"
+  #     m.bytebegin(0) # => 1
+  #     m[3]       # => "113"
+  #     m.bytebegin(3) # => 3
+  #
+  #     m = /(т)(е)(с)/.match('тест')
+  #     # => #<MatchData "тес" 1:"т" 2:"е" 3:"с">
+  #     m[0]       # => "тес"
+  #     m.bytebegin(0) # => 0
+  #     m[3]       # => "с"
+  #     m.bytebegin(3) # => 4
+  #
+  # When string or symbol argument `name` is given, returns the offset of the
+  # beginning for the named match:
+  #
+  #     m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
+  #     # => #<MatchData "hog" foo:"h" bar:"g">
+  #     m[:foo]        # => "h"
+  #     m.bytebegin('foo') # => 0
+  #     m[:bar]        # => "g"
+  #     m.bytebegin(:bar)  # => 2
+  #
+  # Related: MatchData#byteend, MatchData#byteoffset.
+  #
+  def bytebegin: (capture backref) -> Integer?
+
+  # <!--
+  #   rdoc-file=re.c
+  #   - byteend(n) -> integer
+  #   - byteend(name) -> integer
+  # -->
+  # Returns the offset (in bytes) of the end of the specified match.
+  #
+  # When non-negative integer argument `n` is given, returns the offset of the end
+  # of the `n`th match:
+  #
+  #     m = /(.)(.)(\d+)(\d)/.match("THX1138.")
+  #     # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
+  #     m[0]     # => "HX1138"
+  #     m.byteend(0) # => 7
+  #     m[3]     # => "113"
+  #     m.byteend(3) # => 6
+  #
+  #     m = /(т)(е)(с)/.match('тест')
+  #     # => #<MatchData "тес" 1:"т" 2:"е" 3:"с">
+  #     m[0]     # => "тес"
+  #     m.byteend(0) # => 6
+  #     m[3]     # => "с"
+  #     m.byteend(3) # => 6
+  #
+  # When string or symbol argument `name` is given, returns the offset of the end
+  # for the named match:
+  #
+  #     m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
+  #     # => #<MatchData "hog" foo:"h" bar:"g">
+  #     m[:foo]      # => "h"
+  #     m.byteend('foo') # => 1
+  #     m[:bar]      # => "g"
+  #     m.byteend(:bar)  # => 3
+  #
+  # Related: MatchData#bytebegin, MatchData#byteoffset.
+  #
+  def byteend: (capture backref) -> Integer?
+
   # <!--
   #   rdoc-file=re.c
   #   - mtch.byteoffset(n)   -> array

core/ractor.rbs

@@ -249,6 +249,30 @@
 # See [Ractor design doc](rdoc-ref:ractor.md) for more details.
 #
 class Ractor
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - _require(feature)
+  # -->
+  # internal method
+  #
+  def self._require: (String feature) -> bool
+
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - [](sym)
+  # -->
+  # get a value from ractor-local storage of current Ractor
+  #
+  def self.[]: (Symbol) -> untyped
+
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - []=(sym, val)
+  # -->
+  # set a value in ractor-local storage of current Ractor
+  #
+  def self.[]=: (Symbol, untyped) -> untyped
+
   # <!--
   #   rdoc-file=ractor.rb
   #   - count()
@@ -280,7 +304,15 @@ class Ractor
   # -->
   # returns main ractor
   #
-  def self.main: () -> untyped
+  def self.main: () -> Ractor
+
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - main?()
+  # -->
+  # return true if the current ractor is main ractor
+  #
+  def self.main?: () -> boolish
 
   # <!--
   #   rdoc-file=ractor.rb

core/ruby_vm.rbs

@@ -535,6 +535,15 @@ module RubyVM::AbstractSyntaxTree
     #
     def last_column: () -> Integer
 
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - node.locations -> array
+    # -->
+    # Returns location objects associated with the AST node. The returned array
+    # contains RubyVM::AbstractSyntaxTree::Location.
+    #
+    def locations: () -> Array[Location]
+
     # <!--
     #   rdoc-file=ast.rb
     #   - node.tokens -> array
@@ -579,6 +588,54 @@ module RubyVM::AbstractSyntaxTree
     #
     def children: () -> Array[untyped]
   end
+
+  # <!-- rdoc-file=ast.rb -->
+  # RubyVM::AbstractSyntaxTree::Location instances are created by
+  # RubyVM::AbstractSyntaxTree#locations.
+  #
+  # This class is MRI specific.
+  #
+  class Location
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - location.first_column -> integer
+    # -->
+    # The column number in the source code where this AST's text began.
+    #
+    def first_column: () -> Integer
+
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - location.first_lineno -> integer
+    # -->
+    # The line number in the source code where this AST's text began.
+    #
+    def first_lineno: () -> Integer
+
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - location.inspect -> string
+    # -->
+    # Returns debugging information about this location as a string.
+    #
+    def inspect: () -> String
+
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - location.last_lineno -> integer
+    # -->
+    # The line number in the source code where this AST's text ended.
+    #
+    def last_lineno: () -> Integer
+
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - location.last_column -> integer
+    # -->
+    # The column number in the source code where this AST's text ended.
+    #
+    def last_column: () -> Integer
+  end
 end
 
 # <!-- rdoc-file=yjit.rb -->

core/string.rbs

@@ -939,6 +939,30 @@ class String
          | [T < _ToStr] (Regexp regexp, MatchData::capture backref, T replacement) -> T
          | [T < _ToStr] (String substring, T replacement) -> T
 
+  # <!--
+  #   rdoc-file=string.c
+  #   - append_as_bytes(*objects) -> string
+  # -->
+  # Concatenates each object in `objects` into `self` without any encoding
+  # validation or conversion and returns `self`:
+  #
+  #     s = 'foo'
+  #     s.append_as_bytes(" \xE2\x82")  # => "foo \xE2\x82"
+  #     s.valid_encoding?               # => false
+  #     s.append_as_bytes("\xAC 12")
+  #     s.valid_encoding?               # => true
+  #
+  # For each given object `object` that is an Integer, the value is considered a
+  # Byte. If the Integer is bigger than one byte, only the lower byte is
+  # considered, similar to String#setbyte:
+  #
+  #     s = ""
+  #     s.append_as_bytes(0, 257)             # =>  "\u0000\u0001"
+  #
+  # Related: String#<<, String#concat, which do an encoding aware concatenation.
+  #
+  def append_as_bytes: (String) -> String
+
   # <!--
   #   rdoc-file=string.c
   #   - ascii_only? -> true or false