rbs 3.3.1 → 3.4.0.pre.1

data/core/string.rbs

@@ -81,7 +81,7 @@
 # *   `\k<name>` refers to the named capture `name`.
 #
 #
-# See regexp.rdoc for details.
+# See Regexp for details.
 #
 # Note that within the string `replacement`, a character combination such as
 # `$&` is treated as ordinary text, and not as a special match variable.
@@ -92,10 +92,10 @@
 #     text.
 # *   `\'` corresponds to `$'`, which contains string after match.
 # *   `\`` corresponds to `$``, which contains string before match.
-# *   `+` corresponds to `$+`, which contains last capture group.
+# *   `\+` corresponds to `$+`, which contains last capture group.
 #
 #
-# See regexp.rdoc for details.
+# See Regexp for details.
 #
 # Note that `\\\` is interpreted as an escape, i.e., a single backslash.
 #
@@ -279,7 +279,7 @@
 #
 # If argument `capture` is given and not `0`, it should be either an capture
 # group index (integer) or a capture group name (string or symbol); the slice is
-# the specified capture (see Regexp@Capturing):
+# the specified capture (see Regexp@Groups+and+Captures):
 #
 #     s = 'hello there'
 #     s[/[aeiou](.)\1/, 1] # => "l"
@@ -629,6 +629,9 @@
 class String
   include Comparable
 
+  # A `selector` is a special type of string, used within methods like `String#tr`.
+  type selector = string
+
   # <!--
   #   rdoc-file=string.c
   #   - String.try_convert(object) -> object, new_string, or nil
@@ -642,9 +645,76 @@ class String
   #
   # Raises an exception unless `object.to_str` returns a String object.
   #
-  def self.try_convert: (untyped obj) -> String?
+  def self.try_convert: (String object) -> String # technically will return `object` unchanged.
+                      | (_ToStr object) -> String
+                      | (untyped object) -> String?
+
+  # <!--
+  #   rdoc-file=string.c
+  #   - String.new(string = '', **opts) -> new_string
+  # -->
+  # Returns a new String that is a copy of `string`.
+  #
+  # With no arguments, returns the empty string with the Encoding `ASCII-8BIT`:
+  #
+  #     s = String.new
+  #     s # => ""
+  #     s.encoding # => #<Encoding:ASCII-8BIT>
+  #
+  # With optional argument `string` and no keyword arguments, returns a copy of
+  # `string` with the same encoding:
+  #
+  #     String.new('foo')               # => "foo"
+  #     String.new('тест')              # => "тест"
+  #     String.new('こんにちは')          # => "こんにちは"
+  #
+  # (Unlike String.new, a [string
+  # literal](rdoc-ref:syntax/literals.rdoc@String+Literals) like `''` or a [here
+  # document literal](rdoc-ref:syntax/literals.rdoc@Here+Document+Literals) always
+  # has [script encoding](rdoc-ref:encodings.rdoc@Script+Encoding).)
+  #
+  # With optional keyword argument `encoding`, returns a copy of `string` with the
+  # specified encoding; the `encoding` may be an Encoding object, an encoding
+  # name, or an encoding name alias:
+  #
+  #     String.new('foo', encoding: Encoding::US_ASCII).encoding # => #<Encoding:US-ASCII>
+  #     String.new('foo', encoding: 'US-ASCII').encoding         # => #<Encoding:US-ASCII>
+  #     String.new('foo', encoding: 'ASCII').encoding            # => #<Encoding:US-ASCII>
+  #
+  # The given encoding need not be valid for the string's content, and that
+  # validity is not checked:
+  #
+  #     s = String.new('こんにちは', encoding: 'ascii')
+  #     s.valid_encoding? # => false
+  #
+  # But the given `encoding` itself is checked:
+  #
+  #     String.new('foo', encoding: 'bar') # Raises ArgumentError.
+  #
+  # With optional keyword argument `capacity`, returns a copy of `string` (or an
+  # empty string, if `string` is not given); the given `capacity` is advisory
+  # only, and may or may not set the size of the internal buffer, which may in
+  # turn affect performance:
+  #
+  #     String.new(capacity: 1)
+  #     String.new('foo', capacity: 4096)
+  #
+  # The `string`, `encoding`, and `capacity` arguments may all be used together:
+  #
+  #     String.new('hello', encoding: 'UTF-8', capacity: 25)
+  #
+  def initialize: (?string source, ?encoding: encoding?, ?capacity: int?) -> self
 
-  public
+  # <!--
+  #   rdoc-file=string.c
+  #   - replace(other_string) -> self
+  # -->
+  # Replaces the contents of `self` with the contents of `other_string`:
+  #
+  #     s = 'foo'        # => "foo"
+  #     s.replace('bar') # => "bar"
+  #
+  alias initialize_copy replace
 
   # <!--
   #   rdoc-file=string.c
@@ -662,8 +732,8 @@ class String
   #     "foo = %{foo}" % {foo: 'bar'} # => "foo = bar"
   #     "foo = %{foo}, baz = %{baz}" % {foo: 'bar', baz: 'bat'} # => "foo = bar, baz = bat"
   #
-  def %: (Hash[Symbol, untyped]) -> String
-       | (Array[untyped]) -> String
+  def %: (array[untyped] positional_args) -> String
+       | (hash[Symbol, untyped] named_args) -> String
        | (untyped arg) -> String
 
   # <!--
@@ -675,7 +745,7 @@ class String
   #     "Ho! " * 3 # => "Ho! Ho! Ho! "
   #     "Ho! " * 0 # => ""
   #
-  def *: (int n) -> String
+  def *: (int amount) -> String
 
   # <!--
   #   rdoc-file=string.c
@@ -685,7 +755,7 @@ class String
   #
   #     "Hello from " + self.to_s # => "Hello from main"
   #
-  def +: (string other_str) -> String
+  def +: (string other_string) -> String
 
   # <!--
   #   rdoc-file=string.c
@@ -695,20 +765,28 @@ class String
   #
   # Otherwise returns `self.dup`, which is not frozen.
   #
-  def +@: () -> String
+  def +@: () -> self
 
   # <!--
   #   rdoc-file=string.c
   #   - -string -> frozen_string
+  #   - dedup -> frozen_string
   # -->
   # Returns a frozen, possibly pre-existing copy of the string.
   #
   # The returned String will be deduplicated as long as it does not have any
   # instance variables set on it and is not a String subclass.
   #
-  # String#dedup is an alias for String#-@.
+  # Note that `-string` variant is more convenient for defining constants:
+  #
+  #     FILENAME = -'config/database.yml'
+  #
+  # while `dedup` is better suitable for using the method in chains of
+  # calculations:
+  #
+  #     @url_list.concat(urls.map(&:dedup))
   #
-  def -@: () -> String
+  def -@: () -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -728,7 +806,7 @@ class String
   #
   # Related: String#concat, which takes multiple arguments.
   #
-  def <<: (string | Integer str_or_codepoint) -> String
+  def <<: (string | Integer str_or_codepoint) -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -751,8 +829,8 @@ class String
   #     'foo' <=> 'FOO' # => 1
   #     'foo' <=> 1 # => nil
   #
-  def <=>: (string other) -> Integer
-         | (untyped other) -> Integer?
+  def <=>: (string) -> (-1 | 0 | 1)
+         | (untyped) -> (-1 | 0 | 1)?
 
   # <!--
   #   rdoc-file=string.c
@@ -773,7 +851,7 @@ class String
   # If `object` is not an instance of String but responds to `to_str`, then the
   # two strings are compared using `object.==`.
   #
-  def ==: (untyped obj) -> bool
+  def ==: (untyped other) -> bool
 
   # <!-- rdoc-file=string.c -->
   # Returns `true` if `object` has the same length and content; as `self`; `false`
@@ -790,7 +868,7 @@ class String
   # If `object` is not an instance of String but responds to `to_str`, then the
   # two strings are compared using `object.==`.
   #
-  def ===: (untyped obj) -> bool
+  alias === ==
 
   # <!--
   #   rdoc-file=string.c
@@ -804,7 +882,7 @@ class String
   #     'foo' =~ /o/ # => 1
   #     'foo' =~ /x/ # => nil
   #
-  # Note: also updates Regexp@Special+global+variables.
+  # Note: also updates Regexp@Global+Variables.
   #
   # If the given `object` is not a Regexp, returns the value returned by `object
   # =~ self`.
@@ -818,7 +896,12 @@ class String
   #     /(?<number>\d+)/ =~ "no. 9"
   #     number #=> "9"
   #
-  def =~: (untyped obj) -> Integer?
+  def =~: (Regexp regex) -> Integer?
+        | [T] (_MatchAgainst[self, T] object) -> T
+
+  interface _MatchAgainst[O, T]
+    def =~: (O string) -> T
+  end
 
   # <!--
   #   rdoc-file=string.c
@@ -831,12 +914,10 @@ class String
   # Returns the substring of `self` specified by the arguments. See examples at
   # [String Slices](rdoc-ref:String@String+Slices).
   #
-  def []: (int index) -> String?
-        | (int start, int length) -> String?
-        | (Range[Integer] | Range[Integer?] range) -> String?
-        | (Regexp regexp) -> String?
-        | (Regexp regexp, int | String capture) -> String?
-        | (String match_str) -> String?
+  def []: (int start, ?int length) -> String?
+        | (range[int?] range) -> String?
+        | (Regexp regexp, ?MatchData::capture backref) -> String?
+        | (String substring) -> String?
 
   # <!--
   #   rdoc-file=string.c
@@ -863,15 +944,12 @@ class String
   #     s['lly'] = 'ncial' # => "ncial"
   #     s                  # => "financial"
   #
-  # String#slice is an alias for String#[].
-  #
-  def []=: (int pos, String new_str) -> String
-         | (int begin_pos, int end_pos, String new_str) -> String
-         | (Range[Integer] | Range[Integer?] range, String new_str) -> String
-         | (Regexp regexp, String new_str) -> String
-         | (Regexp regexp, int capture, String new_str) -> String
-         | (Regexp regexp, String name, String new_str) -> String
-         | (String other_str, String new_str) -> String
+  def []=: [T < _ToStr] (int index, T replacement) -> T
+         | [T < _ToStr] (int start, int length, T replacement) -> T
+         | [T < _ToStr] (range[int?] range, T replacement) -> T
+         | [T < _ToStr] (Regexp regexp, T replacement) -> T
+         | [T < _ToStr] (Regexp regexp, MatchData::capture backref, T replacement) -> T
+         | [T < _ToStr] (String substring, T replacement) -> T
 
   # <!--
   #   rdoc-file=string.c
@@ -945,7 +1023,7 @@ class String
   #
   # Related: String#index, String#byterindex.
   #
-  def byteindex: (Regexp | string substr_or_regexp, ?int offset) -> Integer?
+  def byteindex: (Regexp | string pattern, ?int offset) -> Integer?
 
   # <!--
   #   rdoc-file=string.c
@@ -1006,7 +1084,7 @@ class String
   #
   # Related: String#byteindex.
   #
-  def byterindex: (Regexp | string substr_or_regexp, ?int offset) -> Integer?
+  def byterindex: (Regexp | string pattern, ?int offset) -> Integer?
 
   # <!--
   #   rdoc-file=string.c
@@ -1020,7 +1098,7 @@ class String
   #     # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175]
   #
   def bytes: () -> Array[Integer]
-           | () { (Integer byte) -> void } -> String
+           | () { (Integer byte) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1082,24 +1160,34 @@ class String
   #     s.byteslice(4).encoding # => #<Encoding:UTF-8>
   #
   def byteslice: (int start, ?int length) -> String?
-               | (Range[Integer] | Range[Integer?] range) -> String?
+               | (range[int?] range) -> String?
 
   # <!--
   #   rdoc-file=string.c
   #   - bytesplice(index, length, str) -> string
-  #   - bytesplice(range, str)         -> string
+  #   - bytesplice(index, length, str, str_index, str_length) -> string
+  #   - bytesplice(range, str) -> string
+  #   - bytesplice(range, str, str_range) -> string
   # -->
   # Replaces some or all of the content of `self` with `str`, and returns `self`.
   # The portion of the string affected is determined using the same criteria as
   # String#byteslice, except that `length` cannot be omitted. If the replacement
   # string is not the same length as the text it is replacing, the string will be
-  # adjusted accordingly. The form that take an Integer will raise an IndexError
-  # if the value is out of range; the Range form will raise a RangeError. If the
-  # beginning or ending offset does not land on character (codepoint) boundary, an
-  # IndexError will be raised.
+  # adjusted accordingly.
+  #
+  # If `str_index` and `str_length`, or `str_range` are given, the content of
+  # `self` is replaced by str.byteslice(str_index, str_length) or
+  # str.byteslice(str_range); however the substring of `str` is not allocated as a
+  # new string.
+  #
+  # The form that take an Integer will raise an IndexError if the value is out of
+  # range; the Range form will raise a RangeError. If the beginning or ending
+  # offset does not land on character (codepoint) boundary, an IndexError will be
+  # raised.
   #
-  def bytesplice: (int index, int length, string str) -> String
-                | (Range[int?], string str) -> String
+  def bytesplice: (int start, int length, string str) -> String
+                | (int start, int length, string str, int str_start, int str_length) -> String
+                | (range[int?] range, string str, ?range[int?] str_range) -> String
 
   # <!--
   #   rdoc-file=string.c
@@ -1138,10 +1226,10 @@ class String
   #
   # Related: String#capitalize.
   #
-  def capitalize!: () -> String?
-                 | (:ascii | :lithuanian | :turkic) -> String?
-                 | (:lithuanian, :turkic) -> String?
-                 | (:turkic, :lithuanian) -> String?
+  def capitalize!: () -> self?
+                 | (:ascii | :lithuanian | :turkic) -> self?
+                 | (:lithuanian, :turkic) -> self?
+                 | (:turkic, :lithuanian) -> self?
 
   # <!--
   #   rdoc-file=string.c
@@ -1168,7 +1256,8 @@ class String
   #
   # Related: String#casecmp?.
   #
-  def casecmp: (untyped other) -> Integer?
+  def casecmp: (string other) -> (-1 | 0 | 1)
+             | (untyped) -> (-1 | 0 | 1)?
 
   # <!--
   #   rdoc-file=string.c
@@ -1191,7 +1280,8 @@ class String
   #
   # Related: String#casecmp.
   #
-  def casecmp?: (untyped other) -> bool?
+  def casecmp?: (string other) -> bool
+              | (untyped) -> bool?
 
   # <!--
   #   rdoc-file=string.c
@@ -1216,7 +1306,7 @@ class String
   #
   # Related: String#ljust, String#rjust.
   #
-  def center: (int width, ?string padstr) -> String
+  def center: (int width, ?string pad_string) -> String
 
   # <!--
   #   rdoc-file=string.c
@@ -1229,7 +1319,7 @@ class String
   #     'こんにちは'.chars # => ["こ", "ん", "に", "ち", "は"]
   #
   def chars: () -> Array[String]
-           | () { (String char) -> void } -> String
+           | () { (String char) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1264,7 +1354,7 @@ class String
   #     'abcd'.chomp('d')  # => "abc"
   #     'abcdd'.chomp('d') # => "abcd"
   #
-  def chomp: (?string separator) -> String
+  def chomp: (?string? separator) -> String
 
   # <!--
   #   rdoc-file=string.c
@@ -1273,7 +1363,9 @@ class String
   # Like String#chomp, but modifies `self` in place; returns `nil` if no
   # modification made, `self` otherwise.
   #
-  def chomp!: (?string separator) -> String?
+  def chomp!: (nil) -> nil
+          # | (?string separator) -> self? # https://github.com/ruby/rbs/pull/1672#discussion_r1423324796
+            | (?string? separator) -> self?
 
   # <!--
   #   rdoc-file=string.c
@@ -1309,7 +1401,7 @@ class String
   #
   # Related: String#chomp!.
   #
-  def chop!: () -> String?
+  def chop!: () -> self?
 
   # <!--
   #   rdoc-file=string.c
@@ -1331,7 +1423,7 @@ class String
   #     s = 'foo' # => "foo"
   #     s.clear   # => ""
   #
-  def clear: () -> String
+  def clear: () -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1344,8 +1436,8 @@ class String
   #     'тест'.codepoints      # => [1090, 1077, 1089, 1090]
   #     'こんにちは'.codepoints # => [12371, 12435, 12395, 12385, 12399]
   #
-  def codepoints: () -> ::Array[Integer]
-                | () { (Integer codepoint) -> void } -> String
+  def codepoints: () -> Array[Integer]
+                | () { (Integer codepoint) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1365,7 +1457,7 @@ class String
   #
   # Related: String#<<, which takes a single argument.
   #
-  def concat: (*string | Integer str_or_codepoint) -> String
+  def concat: (*string | Integer string_or_codepoints) -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1389,7 +1481,7 @@ class String
   #     c.count "\\A"                  #=> 0
   #     c.count "X-\\w"                #=> 3
   #
-  def count: (string other_str, *string other_strs) -> Integer
+  def count: (selector selector_0, *selector more_selectors) -> Integer
 
   # <!--
   #   rdoc-file=string.c
@@ -1453,7 +1545,14 @@ class String
   # The returned String will be deduplicated as long as it does not have any
   # instance variables set on it and is not a String subclass.
   #
-  # String#dedup is an alias for String#-@.
+  # Note that `-string` variant is more convenient for defining constants:
+  #
+  #     FILENAME = -'config/database.yml'
+  #
+  # while `dedup` is better suitable for using the method in chains of
+  # calculations:
+  #
+  #     @url_list.concat(urls.map(&:dedup))
   #
   alias dedup -@
 
@@ -1470,7 +1569,7 @@ class String
   #     "hello".delete "aeiou", "^e"   #=> "hell"
   #     "hello".delete "ej-m"          #=> "ho"
   #
-  def delete: (string other_str, *string other_strs) -> String
+  def delete: (selector selector_0, *selector more_selectors) -> String
 
   # <!--
   #   rdoc-file=string.c
@@ -1479,7 +1578,7 @@ class String
   # Like String#delete, but modifies `self` in place. Returns `self` if any
   # changes were made, `nil` otherwise.
   #
-  def delete!: (string other_str, *string other_strs) -> String?
+  def delete!: (selector selector_0, *selector more_selectors) -> self?
 
   # <!--
   #   rdoc-file=string.c
@@ -1503,7 +1602,7 @@ class String
   # Like String#delete_prefix, except that `self` is modified in place. Returns
   # `self` if the prefix is removed, `nil` otherwise.
   #
-  def delete_prefix!: (string prefix) -> String?
+  def delete_prefix!: (string prefix) -> self?
 
   # <!--
   #   rdoc-file=string.c
@@ -1527,7 +1626,7 @@ class String
   # Like String#delete_suffix, except that `self` is modified in place. Returns
   # `self` if the suffix is removed, `nil` otherwise.
   #
-  def delete_suffix!: (string suffix) -> String?
+  def delete_suffix!: (string suffix) -> self?
 
   # <!--
   #   rdoc-file=string.c
@@ -1565,10 +1664,10 @@ class String
   #
   # Related: String#downcase, String#upcase, String#upcase!.
   #
-  def downcase!: () -> String?
-               | (:ascii | :fold | :lithuanian | :turkic) -> String?
-               | (:lithuanian, :turkic) -> String?
-               | (:turkic, :lithuanian) -> String?
+  def downcase!: () -> self?
+               | (:ascii | :fold | :lithuanian | :turkic) -> self?
+               | (:lithuanian, :turkic) -> self?
+               | (:turkic, :lithuanian) -> self?
 
   # <!--
   #   rdoc-file=string.c
@@ -1607,8 +1706,8 @@ class String
   #
   # Returns an enumerator if no block is given.
   #
-  def each_byte: () { (Integer byte) -> void } -> self
-               | () -> ::Enumerator[Integer, self]
+  def each_byte: () -> Enumerator[Integer, self]
+               | () { (Integer byte) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1633,8 +1732,8 @@ class String
   #
   # Returns an enumerator if no block is given.
   #
-  def each_char: () { (String char) -> void } -> self
-               | () -> ::Enumerator[String, self]
+  def each_char: () -> Enumerator[String, self]
+               | () { (String char) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1659,8 +1758,8 @@ class String
   #
   # Returns an enumerator if no block is given.
   #
-  def each_codepoint: () { (Integer codepoint) -> void } -> self
-                    | () -> ::Enumerator[Integer, self]
+  def each_codepoint: () -> Enumerator[Integer, self]
+                    | () { (Integer codepoint) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1681,8 +1780,8 @@ class String
   #
   # Returns an enumerator if no block is given.
   #
-  def each_grapheme_cluster: () { (String grapheme) -> void } -> self
-                           | () -> ::Enumerator[String, self]
+  def each_grapheme_cluster: () -> Enumerator[String, self]
+                           | () { (String grapheme_cluter) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1747,8 +1846,8 @@ class String
   #
   # With no block given, returns an enumerator.
   #
-  def each_line: (?string separator, ?chomp: boolish) { (String line) -> void } -> self
-               | (?string separator, ?chomp: boolish) -> Enumerator[String, self]
+  def each_line: (?string? separator, ?chomp: boolish) -> Enumerator[String, self]
+               | (?string? separator, ?chomp: boolish) { (String line) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1763,7 +1862,7 @@ class String
   def empty?: () -> bool
 
   # <!--
-  #   rdoc-file=transcode.rdoc
+  #   rdoc-file=transcode.c
   #   - encode(dst_encoding = Encoding.default_internal, **enc_opts) -> string
   #   - encode(dst_encoding, src_encoding, **enc_opts)   -> string
   # -->
@@ -1809,7 +1908,30 @@ class String
   # Optional keyword arguments `enc_opts` specify encoding options; see [Encoding
   # Options](rdoc-ref:encodings.rdoc@Encoding+Options).
   #
-  def encode: (?encoding encoding, ?encoding from_encoding, ?invalid: :replace ?, ?undef: :replace ?, ?replace: String, ?fallback: String::encode_fallback, ?xml: :text | :attr, ?universal_newline: true, ?cr_newline: true, ?crlf_newline: true) -> String
+  # Please note that, unless `invalid: :replace` option is given, conversion from
+  # an encoding `enc` to the same encoding `enc` (independent of whether `enc` is
+  # given explicitly or implicitly) is a no-op, i.e. the string is simply copied
+  # without any changes, and no exceptions are raised, even if there are invalid
+  # bytes.
+  #
+  def encode: (
+    ?encoding source_encoding,
+    ?encoding? from_encoding,
+    ?invalid: :replace ?,
+    ?undef: :replace ?,
+    ?replace: string?,
+    ?xml: (:text | :attr)?,
+    ?newline: (:universal | :crlf | :cr | :lf)?,
+    ?universal_newline: boolish,
+    ?cr_newline: boolish,
+    ?crlf_newline: boolish,
+    ?lf_newline: boolish,
+    ?fallback: ^(String) -> string? | Method | _EncodeFallbackAref
+  ) -> instance
+
+  interface _EncodeFallbackAref
+    def []: (String) -> string?
+  end
 
   # <!--
   #   rdoc-file=transcode.c
@@ -1818,7 +1940,20 @@ class String
   # -->
   # Like #encode, but applies encoding changes to `self`; returns `self`.
   #
-  def encode!: (?encoding encoding, ?encoding from_encoding, ?invalid: :replace ?, ?undef: :replace ?, ?replace: String, ?fallback: String::encode_fallback, ?xml: :text | :attr, ?universal_newline: true, ?cr_newline: true, ?crlf_newline: true) -> self
+  def encode!: (
+    ?encoding source_encoding,
+    ?encoding? from_encoding,
+    ?invalid: :replace ?,
+    ?undef: :replace ?,
+    ?replace: string?,
+    ?xml: (:text | :attr)?,
+    ?newline: (:universal | :crlf | :cr | :lf)?,
+    ?universal_newline: boolish,
+    ?cr_newline: boolish,
+    ?crlf_newline: boolish,
+    ?lf_newline: boolish,
+    ?fallback: ^(String) -> string? | Method | _EncodeFallbackAref
+  ) -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1888,7 +2023,7 @@ class String
   #     s.force_encoding(Encoding::UTF_8) # => "łał"
   #     s.valid_encoding?                 # => true
   #
-  def force_encoding: (string | Encoding encoding) -> self
+  def force_encoding: (encoding enc) -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1926,7 +2061,8 @@ class String
   #     s.grapheme_clusters
   #     # => ["ä", "-", "p", "q", "r", "-", "b̈", "-", "x", "y", "z", "-", "c̈"]
   #
-  def grapheme_clusters: () -> ::Array[::String]
+  def grapheme_clusters: () -> Array[String]
+                       | () { (String grapheme_cluter) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -1942,10 +2078,9 @@ class String
   #
   # Related: String#sub, String#sub!, String#gsub!.
   #
-  def gsub: (Regexp | string pattern, string replacement) -> String
-          | (Regexp | string pattern, Hash[String, String] hash) -> String
+  def gsub: (Regexp | string pattern, string | hash[String, _ToS] replacement) -> String
+          | (Regexp | string pattern) -> Enumerator[String, String]
           | (Regexp | string pattern) { (String match) -> _ToS } -> String
-          | (Regexp | string pattern) -> ::Enumerator[String, self]
 
   # <!--
   #   rdoc-file=string.c
@@ -1962,10 +2097,9 @@ class String
   #
   # Related: String#sub, String#gsub, String#sub!.
   #
-  def gsub!: (Regexp | string pattern, string replacement) -> String?
-           | (Regexp | string pattern, Hash[String, String] hash) -> String?
-           | (Regexp | string pattern) { (String match) -> _ToS } -> String?
-           | (Regexp | string pattern) -> ::Enumerator[String, self]
+  def gsub!: (Regexp | string pattern, string | hash[String, _ToS] replacement) -> self?
+           | (Regexp | string pattern) -> Enumerator[String, self]
+           | (Regexp | string pattern) { (String match) -> _ToS } -> self?
 
   # <!--
   #   rdoc-file=string.c
@@ -2006,7 +2140,7 @@ class String
   #     s.include?('fo')   # => true
   #     s.include?('food') # => false
   #
-  def include?: (string other_str) -> bool
+  def include?: (string other_string) -> bool
 
   # <!--
   #   rdoc-file=string.c
@@ -2052,7 +2186,7 @@ class String
   #
   # Related: String#rindex.
   #
-  def index: (Regexp | string substr_or_regexp, ?int offset) -> Integer?
+  def index: (Regexp | string pattern, ?int offset) -> Integer?
 
   # <!--
   #   rdoc-file=string.c
@@ -2069,7 +2203,7 @@ class String
   #
   #     'foo'.insert(-2, 'bar') # => "fobaro"
   #
-  def insert: (int index, string other_str) -> String
+  def insert: (int index, string other_str) -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -2121,8 +2255,6 @@ class String
   #     'тест'.bytesize       # => 8
   #     'こんにちは'.bytesize   # => 15
   #
-  # String#size is an alias for String#length.
-  #
   def length: () -> Integer
 
   # <!--
@@ -2132,7 +2264,8 @@ class String
   # Forms substrings ("lines") of `self` according to the given arguments (see
   # String#each_line for details); returns the lines in an array.
   #
-  def lines: (?string separator, ?chomp: boolish) -> Array[String]
+  def lines: (?string? separator, ?chomp: boolish) -> Array[String]
+           | (?string? separator, ?chomp: boolish) { (String line) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -2157,7 +2290,7 @@ class String
   #
   # Related: String#rjust, String#center.
   #
-  def ljust: (int integer, ?string padstr) -> String
+  def ljust: (int size, ?string pad_string) -> String
 
   # <!--
   #   rdoc-file=string.c
@@ -2193,7 +2326,7 @@ class String
   # -->
   # Returns a MatchData object (or `nil`) based on `self` and the given `pattern`.
   #
-  # Note: also updates Regexp@Special+global+variables.
+  # Note: also updates Regexp@Global+Variables.
   #
   # *   Computes `regexp` by converting `pattern` (if not already a Regexp).
   #         regexp = Regexp.new(pattern)
@@ -2221,8 +2354,8 @@ class String
   #     'foo'.match(/x/) {|matchdata| matchdata } # => nil
   #     'foo'.match(/f/, 1) {|matchdata| matchdata } # => nil
   #
-  def match: (Regexp | string pattern, ?int pos) -> MatchData?
-           | [A] (Regexp | string pattern, ?int pos) { (MatchData) -> A } -> A
+  def match: (Regexp | string pattern, ?int offset) -> MatchData?
+           | [T] (Regexp | string pattern, ?int offset) { (MatchData matchdata) -> T } -> T?
 
   # <!--
   #   rdoc-file=string.c
@@ -2231,7 +2364,7 @@ class String
   # Returns `true` or `false` based on whether a match is found for `self` and
   # `pattern`.
   #
-  # Note: does not update Regexp@Special+global+variables.
+  # Note: does not update Regexp@Global+Variables.
   #
   # Computes `regexp` by converting `pattern` (if not already a Regexp).
   #     regexp = Regexp.new(pattern)
@@ -2247,7 +2380,7 @@ class String
   #     'foo'.match?('f', 1) # => false
   #     'foo'.match?('o', 1) # => true
   #
-  def match?: (Regexp | string pattern, ?int pos) -> bool
+  def match?: (Regexp | string pattern, ?int offset) -> bool
 
   # <!-- rdoc-file=string.c -->
   # Returns the successor to `self`. The successor is calculated by incrementing
@@ -2301,16 +2434,12 @@ class String
   #
   #     ''.succ # => ""
   #
-  # String#next is an alias for String#succ.
-  #
-  def next: () -> String
+  alias next succ
 
   # <!-- rdoc-file=string.c -->
   # Equivalent to String#succ, but modifies `self` in place; returns `self`.
   #
-  # String#next! is an alias for String#succ!.
-  #
-  def next!: () -> self
+  alias next! succ!
 
   # <!--
   #   rdoc-file=string.c
@@ -2373,7 +2502,7 @@ class String
   #
   # Related: String#rpartition, String#split.
   #
-  def partition: (Regexp | string sep_or_regexp) -> [ String, String, String ]
+  def partition: (Regexp | string pattern) -> [String, String, String]
 
   # <!--
   #   rdoc-file=string.c
@@ -2387,7 +2516,7 @@ class String
   #
   # Related: String#concat.
   #
-  def prepend: (*string other_strs) -> String
+  def prepend: (*string other_strings) -> self
 
   # <!-- rdoc-file=string.c -->
   # Replaces the contents of `self` with the contents of `other_string`:
@@ -2395,7 +2524,7 @@ class String
   #     s = 'foo'        # => "foo"
   #     s.replace('bar') # => "bar"
   #
-  def replace: (string other_str) -> String
+  def replace: (string other_string) -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -2475,7 +2604,7 @@ class String
   #
   # Related: String#index.
   #
-  def rindex: (string | Regexp substr_or_regexp, ?int pos) -> Integer?
+  def rindex: (Regexp | string pattern, ?int offset) -> Integer?
 
   # <!--
   #   rdoc-file=string.c
@@ -2500,7 +2629,7 @@ class String
   #
   # Related: String#ljust, String#center.
   #
-  def rjust: (int integer, ?string padstr) -> String
+  def rjust: (int size, ?string pad_string) -> String
 
   # <!--
   #   rdoc-file=string.c
@@ -2532,7 +2661,7 @@ class String
   #
   # Related: String#partition, String#split.
   #
-  def rpartition: (string | Regexp sep_or_regexp) -> [ String, String, String ]
+  def rpartition: (Regexp | string pattern) -> [String, String, String]
 
   # <!--
   #   rdoc-file=string.c
@@ -2601,9 +2730,9 @@ class String
   #     rceu lowlr
   #
   def scan: (Regexp pattern) -> Array[String | Array[String]]
-          | (Regexp pattern) { (String | Array[String]) -> void } -> self
+          | (Regexp pattern) { (String | Array[String] matches) -> void } -> self
           | (string pattern) -> Array[String]
-          | (string pattern) { (String) -> void } -> self
+          | (string pattern) { (String match) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -2635,8 +2764,8 @@ class String
   #     "\x81"
   #     "\x81"
   #
-  def scrub: (?string repl) -> String
-           | () { (String bytes) -> string } -> String
+  def scrub: (?string? replacement) -> String
+           | (?nil) { (String bytes) -> string } -> String
 
   # <!--
   #   rdoc-file=string.c
@@ -2646,8 +2775,8 @@ class String
   # -->
   # Like String#scrub, except that any replacements are made in `self`.
   #
-  def scrub!: (?string repl) -> self
-            | () { (String bytes) -> string } -> self
+  def scrub!: (?string? replacement) -> self
+            | (?nil) { (String bytes) -> string } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -2661,7 +2790,7 @@ class String
   #
   # Related: String#getbyte.
   #
-  def setbyte: (int index, int integer) -> int
+  def setbyte: [T < _ToInt] (int index, T byte) -> T
 
   # <!-- rdoc-file=string.c -->
   # Returns the count of characters (not bytes) in `self`:
@@ -2676,8 +2805,6 @@ class String
   #     'тест'.bytesize       # => 8
   #     'こんにちは'.bytesize   # => 15
   #
-  # String#size is an alias for String#length.
-  #
   alias size length
 
   # <!-- rdoc-file=string.c -->
@@ -2706,10 +2833,10 @@ class String
   #     string.slice!("r")      #=> "r"
   #     string                  #=> "Thing"
   #
-  def slice!: (int integer, ?int integer) -> String?
-            | (Range[Integer] | Range[Integer?] range) -> String?
-            | (Regexp regexp, ?int | String capture) -> String?
-            | (String other_str) -> String?
+  def slice!: (int index, ?int length) -> String?
+            | (range[int?] range) -> String?
+            | (String substring) -> String?
+            | (Regexp regexp, ?MatchData::capture backref) -> String?
 
   # <!--
   #   rdoc-file=string.c
@@ -2797,8 +2924,8 @@ class String
   #
   # Related: String#partition, String#rpartition.
   #
-  def split: (?Regexp | string pattern, ?int limit) -> Array[String]
-           | (?Regexp | string pattern, ?int limit) { (String) -> void } -> self
+  def split: (?Regexp | string | nil pattern, ?int limit) -> Array[String]
+           | (?Regexp | string | nil pattern, ?int limit) { (String substring) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -2816,7 +2943,7 @@ class String
   #     "  now   is  the".squeeze(" ")         #=> " now is the"
   #     "putters shoot balls".squeeze("m-z")   #=> "puters shot balls"
   #
-  def squeeze: (*string other_str) -> String
+  def squeeze: (*selector selectors) -> String
 
   # <!--
   #   rdoc-file=string.c
@@ -2825,7 +2952,7 @@ class String
   # Like String#squeeze, but modifies `self` in place. Returns `self` if any
   # changes were made, `nil` otherwise.
   #
-  def squeeze!: (*string other_str) -> self?
+  def squeeze!: (*selector selectors) -> self?
 
   # <!--
   #   rdoc-file=string.c
@@ -2851,7 +2978,7 @@ class String
   #
   # Related: String#end_with?.
   #
-  def start_with?: (*string prefixes) -> bool
+  def start_with?: (*Regexp | string prefixes) -> bool
 
   # <!--
   #   rdoc-file=string.c
@@ -2892,7 +3019,7 @@ class String
   #
   # Related: String#sub!, String#gsub, String#gsub!.
   #
-  def sub: (Regexp | string pattern, string | Hash[String, String] replacement) -> String
+  def sub: (Regexp | string pattern, string | hash[String, _ToS] replacement) -> String
          | (Regexp | string pattern) { (String match) -> _ToS } -> String
 
   # <!--
@@ -2907,8 +3034,8 @@ class String
   #
   # Related: String#sub, String#gsub, String#gsub!.
   #
-  def sub!: (Regexp | string pattern, string | Hash[String, String] replacement) -> self?
-          | (Regexp | string pattern) { (String match) -> _ToS } -> String?
+  def sub!: (Regexp | string pattern, string | hash[String, _ToS] replacement) -> self?
+          | (Regexp | string pattern) { (String match) -> _ToS } -> self?
 
   # <!--
   #   rdoc-file=string.c
@@ -2965,8 +3092,6 @@ class String
   #
   #     ''.succ # => ""
   #
-  # String#next is an alias for String#succ.
-  #
   def succ: () -> String
 
   # <!--
@@ -2975,9 +3100,7 @@ class String
   # -->
   # Equivalent to String#succ, but modifies `self` in place; returns `self`.
   #
-  # String#next! is an alias for String#succ!.
-  #
-  def succ!: () -> String
+  def succ!: () -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -2994,7 +3117,7 @@ class String
   #
   # This is not a particularly strong checksum.
   #
-  def sum: (?int n) -> Integer
+  def sum: (?int bits) -> Integer
 
   # <!--
   #   rdoc-file=string.c
@@ -3117,7 +3240,7 @@ class String
   #     'abcdef'.to_i # => 0
   #     '2'.to_i(2)   # => 0
   #
-  def to_i: (?int base) -> Integer
+  def to_i: (?int radix) -> Integer
 
   # <!--
   #   rdoc-file=rational.c
@@ -3155,17 +3278,13 @@ class String
   # Returns `self` if `self` is a String, or `self` converted to a String if
   # `self` is a subclass of String.
   #
-  # String#to_str is an alias for String#to_s.
-  #
   def to_s: () -> String
 
   # <!-- rdoc-file=string.c -->
   # Returns `self` if `self` is a String, or `self` converted to a String if
   # `self` is a subclass of String.
   #
-  # String#to_str is an alias for String#to_s.
-  #
-  def to_str: () -> String
+  alias to_str to_s
 
   # <!-- rdoc-file=string.c -->
   # Returns the Symbol corresponding to *str*, creating the symbol if it did not
@@ -3182,7 +3301,7 @@ class String
   #
   #     'cat and dog'.to_sym   #=> :"cat and dog"
   #
-  def to_sym: () -> Symbol
+  alias to_sym intern
 
   # <!--
   #   rdoc-file=string.c
@@ -3222,7 +3341,7 @@ class String
   #     'i-b-m'.tr('b\-z', 'a-z')       # => "ibabm"     # Escaped embedded hyphen.
   #     'foo\\bar'.tr('ab\\', 'XYZ')    # => "fooZYXr"   # Escaped backslash.
   #
-  def tr: (string from_str, string to_str) -> String
+  def tr: (selector source, string relpacement) -> String
 
   # <!--
   #   rdoc-file=string.c
@@ -3231,7 +3350,7 @@ class String
   # Like String#tr, but modifies `self` in place. Returns `self` if any changes
   # were made, `nil` otherwise.
   #
-  def tr!: (string from_str, string to_str) -> String?
+  def tr!: (selector source, string relpacement) -> self?
 
   # <!--
   #   rdoc-file=string.c
@@ -3246,7 +3365,7 @@ class String
   #
   # Related: String#squeeze.
   #
-  def tr_s: (string from_str, string to_str) -> String
+  def tr_s: (selector source, string replacement) -> String
 
   # <!--
   #   rdoc-file=string.c
@@ -3257,7 +3376,7 @@ class String
   #
   # Related: String#squeeze!.
   #
-  def tr_s!: (string from_str, string to_str) -> String?
+  def tr_s!: (selector source, string replacement) -> self?
 
   # <!--
   #   rdoc-file=string.c
@@ -3309,7 +3428,7 @@ class String
   #
   # Related: String#unicode_normalize!, String#unicode_normalized?.
   #
-  def unicode_normalize: (?:nfc | :nfd | :nfkc | :nfkd) -> String
+  def unicode_normalize: (?:nfc | :nfd | :nfkc | :nfkd form) -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -3320,7 +3439,7 @@ class String
   #
   # Related String#unicode_normalized?.
   #
-  def unicode_normalize!: (?:nfc | :nfd | :nfkc | :nfkd) -> String
+  def unicode_normalize!: (?:nfc | :nfd | :nfkc | :nfkd form) -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -3353,7 +3472,8 @@ class String
   # Extracts data from `self`, forming objects that become the elements of a new
   # array; returns that array. See [Packed Data](rdoc-ref:packed_data.rdoc).
   #
-  def unpack: (String format, ?offset: Integer) -> Array[Integer | Float | String | nil]
+  def unpack: (string template, ?offset: int) -> Array[Integer | Float | String | nil]
+            | (string template, ?offset: int) { (Integer | Float | String | nil value) -> void } -> nil
 
   # <!--
   #   rdoc-file=pack.rb
@@ -3362,7 +3482,7 @@ class String
   # Like String#unpack, but unpacks and returns only the first extracted object.
   # See [Packed Data](rdoc-ref:packed_data.rdoc).
   #
-  def unpack1: (String format) -> (Integer | Float | String | nil)
+  def unpack1: (string template, ?offset: int) -> (Integer | Float | String)?
 
   # <!--
   #   rdoc-file=string.c
@@ -3439,8 +3559,8 @@ class String
   #
   #     'a8'.upto('b6') # => #<Enumerator: "a8":upto("b6")>
   #
-  def upto: (string other_str, ?boolish exclusive) -> Enumerator[String, self]
-          | (string other_str, ?boolish exclusive) { (String s) -> void } -> self
+  def upto: (string other_string, ?boolish exclusive) -> Enumerator[String, self]
+          | (string other_string, ?boolish exclusive) { (String s) -> void } -> self
 
   # <!--
   #   rdoc-file=string.c
@@ -3453,79 +3573,12 @@ class String
   #     "\x80".force_encoding("UTF-8").valid_encoding?     # => false
   #
   def valid_encoding?: () -> bool
-
-  private
-
-  # <!--
-  #   rdoc-file=string.c
-  #   - String.new(string = '', **opts) -> new_string
-  # -->
-  # Returns a new String that is a copy of `string`.
-  #
-  # With no arguments, returns the empty string with the Encoding `ASCII-8BIT`:
-  #
-  #     s = String.new
-  #     s # => ""
-  #     s.encoding # => #<Encoding:ASCII-8BIT>
-  #
-  # With optional argument `string` and no keyword arguments, returns a copy of
-  # `string` with the same encoding:
-  #
-  #     String.new('foo')               # => "foo"
-  #     String.new('тест')              # => "тест"
-  #     String.new('こんにちは')          # => "こんにちは"
-  #
-  # (Unlike String.new, a [string
-  # literal](rdoc-ref:syntax/literals.rdoc@String+Literals) like `''` or a [here
-  # document literal](rdoc-ref:syntax/literals.rdoc@Here+Document+Literals) always
-  # has [script encoding](rdoc-ref:encodings.rdoc@Script+Encoding).)
-  #
-  # With optional keyword argument `encoding`, returns a copy of `string` with the
-  # specified encoding; the `encoding` may be an Encoding object, an encoding
-  # name, or an encoding name alias:
-  #
-  #     String.new('foo', encoding: Encoding::US_ASCII).encoding # => #<Encoding:US-ASCII>
-  #     String.new('foo', encoding: 'US-ASCII').encoding         # => #<Encoding:US-ASCII>
-  #     String.new('foo', encoding: 'ASCII').encoding            # => #<Encoding:US-ASCII>
-  #
-  # The given encoding need not be valid for the string's content, and that
-  # validity is not checked:
-  #
-  #     s = String.new('こんにちは', encoding: 'ascii')
-  #     s.valid_encoding? # => false
-  #
-  # But the given `encoding` itself is checked:
-  #
-  #     String.new('foo', encoding: 'bar') # Raises ArgumentError.
-  #
-  # With optional keyword argument `capacity`, returns a copy of `string` (or an
-  # empty string, if `string` is not given); the given `capacity` is advisory
-  # only, and may or may not set the size of the internal buffer, which may in
-  # turn affect performance:
-  #
-  #     String.new(capacity: 1)
-  #     String.new('foo', capacity: 4096)
-  #
-  # The `string`, `encoding`, and `capacity` arguments may all be used together:
-  #
-  #     String.new('hello', encoding: 'UTF-8', capacity: 25)
-  #
-  def initialize: (?string str, ?encoding: encoding, ?capacity: int) -> void
-
-  # <!--
-  #   rdoc-file=string.c
-  #   - replace(other_string) -> self
-  # -->
-  # Replaces the contents of `self` with the contents of `other_string`:
-  #
-  #     s = 'foo'        # => "foo"
-  #     s.replace('bar') # => "bar"
-  #
-  alias initialize_copy replace
 end
 
+%a{steep:deprecated}
 interface _ArefFromStringToString
   def []: (String) -> String
 end
 
+%a{steep:deprecated}
 type String::encode_fallback = Hash[String, String] | Proc | Method | _ArefFromStringToString