rbs 3.7.0 → 3.8.0

data/core/string.rbs

@@ -1,99 +1,93 @@
 # <!-- rdoc-file=string.rb -->
-# A String object has an arbitrary sequence of bytes, typically representing
-# text or binary data. A String object may be created using String::new or as
+# A `String` object has an arbitrary sequence of bytes, typically representing
+# text or binary data. A `String` object may be created using String::new or as
 # literals.
 #
 # String objects differ from Symbol objects in that Symbol objects are designed
 # to be used as identifiers, instead of text or data.
 #
-# You can create a String object explicitly with:
+# You can create a `String` object explicitly with:
 #
 # *   A [string literal](rdoc-ref:syntax/literals.rdoc@String+Literals).
 # *   A [heredoc literal](rdoc-ref:syntax/literals.rdoc@Here+Document+Literals).
 #
-#
 # You can convert certain objects to Strings with:
 #
 # *   Method #String.
 #
-#
-# Some String methods modify `self`. Typically, a method whose name ends with
-# `!` modifies `self` and returns `self`; often a similarly named method
+# Some `String` methods modify `self`. Typically, a method whose name ends with
+# `!` modifies `self` and returns `self`; often, a similarly named method
 # (without the `!`) returns a new string.
 #
-# In general, if there exist both bang and non-bang version of method, the bang!
-# mutates and the non-bang! does not. However, a method without a bang can also
-# mutate, such as String#replace.
+# In general, if both bang and non-bang versions of a method exist, the bang
+# method mutates and the non-bang method does not. However, a method without a
+# bang can also mutate, such as String#replace.
 #
 # ## Substitution Methods
 #
 # These methods perform substitutions:
 #
 # *   String#sub: One substitution (or none); returns a new string.
-# *   String#sub!: One substitution (or none); returns `self`.
+# *   String#sub!: One substitution (or none); returns `self` if any changes,
+#     `nil` otherwise.
 # *   String#gsub: Zero or more substitutions; returns a new string.
-# *   String#gsub!: Zero or more substitutions; returns `self`.
-#
+# *   String#gsub!: Zero or more substitutions; returns `self` if any changes,
+#     `nil` otherwise.
 #
 # Each of these methods takes:
 #
-# *   A first argument, `pattern` (string or regexp), that specifies the
+# *   A first argument, `pattern` (String or Regexp), that specifies the
 #     substring(s) to be replaced.
 #
-# *   Either of these:
+# *   Either of the following:
 #
-#     *   A second argument, `replacement` (string or hash), that determines the
+#     *   A second argument, `replacement` (String or Hash), that determines the
 #         replacing string.
 #     *   A block that will determine the replacing string.
 #
-#
-#
-# The examples in this section mostly use methods String#sub and String#gsub;
-# the principles illustrated apply to all four substitution methods.
+# The examples in this section mostly use the String#sub and String#gsub
+# methods; the principles illustrated apply to all four substitution methods.
 #
 # **Argument `pattern`**
 #
 # Argument `pattern` is commonly a regular expression:
 #
 #     s = 'hello'
-#     s.sub(/[aeiou]/, '*')# => "h*llo"
+#     s.sub(/[aeiou]/, '*') # => "h*llo"
 #     s.gsub(/[aeiou]/, '*') # => "h*ll*"
-#     s.gsub(/[aeiou]/, '')# => "hll"
-#     s.sub(/ell/, 'al')   # => "halo"
-#     s.gsub(/xyzzy/, '*') # => "hello"
+#     s.gsub(/[aeiou]/, '')  # => "hll"
+#     s.sub(/ell/, 'al')     # => "halo"
+#     s.gsub(/xyzzy/, '*')   # => "hello"
 #     'THX1138'.gsub(/\d+/, '00') # => "THX00"
 #
 # When `pattern` is a string, all its characters are treated as ordinary
-# characters (not as regexp special characters):
+# characters (not as Regexp special characters):
 #
 #     'THX1138'.gsub('\d+', '00') # => "THX1138"
 #
-# **\String `replacement`**
+# **`String` `replacement`**
 #
-# If `replacement` is a string, that string will determine the replacing string
-# that is to be substituted for the matched text.
+# If `replacement` is a string, that string determines the replacing string that
+# is substituted for the matched text.
 #
 # Each of the examples above uses a simple string as the replacing string.
 #
-# String `replacement` may contain back-references to the pattern's captures:
+# `String` `replacement` may contain back-references to the pattern's captures:
 #
-# *   `\n` (*n* a non-negative integer) refers to `$n`.
+# *   `\n` (*n* is a non-negative integer) refers to `$n`.
 # *   `\k<name>` refers to the named capture `name`.
 #
-#
 # 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.
-# However, you may refer to some special match variables using these
-# combinations:
+# `$&` is treated as ordinary text, not as a special match variable. However,
+# you may refer to some special match variables using these combinations:
 #
 # *   `\&` and `\0` correspond to `$&`, which contains the complete matched
 #     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 the string after the match.
+# *   `\`` corresponds to `$``, which contains the string before the match.
+# *   `\+` corresponds to `$+`, which contains the last capture group.
 #
 # See Regexp for details.
 #
@@ -108,16 +102,16 @@
 # double-quoted string literal, you need to write `"..\\\\&.."`.
 #
 # If you want to write a non-back-reference string `\&` in `replacement`, you
-# need first to escape the backslash to prevent this method from interpreting it
+# need to first escape the backslash to prevent this method from interpreting it
 # as a back-reference, and then you need to escape the backslashes again to
 # prevent a string literal from consuming them: `"..\\\\\\\\&.."`.
 #
-# You may want to use the block form to avoid a lot of backslashes.
+# You may want to use the block form to avoid excessive backslashes.
 #
 # **\Hash `replacement`**
 #
-# If argument `replacement` is a hash, and `pattern` matches one of its keys,
-# the replacing string is the value for that key:
+# If the argument `replacement` is a hash, and `pattern` matches one of its
+# keys, the replacing string is the value for that key:
 #
 #     h = {'foo' => 'bar', 'baz' => 'bat'}
 #     'food'.sub('foo', h) # => "bard"
@@ -132,15 +126,15 @@
 # In the block form, the current match string is passed to the block; the
 # block's return value becomes the replacing string:
 #
-#      s = '@'
-#     '1234'.gsub(/\d/) {|match| s.succ! } # => "ABCD"
+#     s = '@'
+#     '1234'.gsub(/\d/) { |match| s.succ! } # => "ABCD"
 #
 # Special match variables such as `$1`, `$2`, `$``, `$&`, and `$'` are set
 # appropriately.
 #
 # ## Whitespace in Strings
 #
-# In class String, *whitespace* is defined as a contiguous sequence of
+# In the class `String`, *whitespace* is defined as a contiguous sequence of
 # characters consisting of any mixture of the following:
 #
 # *   NL (null): `"\x00"`, `"\u0000"`.
@@ -151,55 +145,51 @@
 # *   CR (carriage return): `"\x0d"`, `"\r"`.
 # *   SP (space): `"\x20"`, `" "`.
 #
+# Whitespace is relevant for the following methods:
 #
-# Whitespace is relevant for these methods:
-#
-# *   #lstrip, #lstrip!: strip leading whitespace.
-# *   #rstrip, #rstrip!: strip trailing whitespace.
-# *   #strip, #strip!: strip leading and trailing whitespace.
-#
+# *   #lstrip, #lstrip!: Strip leading whitespace.
+# *   #rstrip, #rstrip!: Strip trailing whitespace.
+# *   #strip, #strip!: Strip leading and trailing whitespace.
 #
-# ## String Slices
+# ## `String` Slices
 #
-# A *slice* of a string is a substring that is selected by certain criteria.
+# A *slice* of a string is a substring selected by certain criteria.
 #
-# These instance methods make use of slicing:
-#
-# *   String#[] (also aliased as String#slice) returns a slice copied from
-#     `self`.
-# *   String#[]= returns a copy of `self` with a slice replaced.
-# *   String#slice! returns `self` with a slice removed.
+# These instance methods utilize slicing:
 #
+# *   String#[] (aliased as String#slice): Returns a slice copied from `self`.
+# *   String#[]=: Mutates `self` with the slice replaced.
+# *   String#slice!: Mutates `self` with the slice removed and returns the
+#     removed slice.
 #
 # Each of the above methods takes arguments that determine the slice to be
 # copied or replaced.
 #
-# The arguments have several forms. For string `string`,  the forms are:
-#
-# *   `string[index]`.
-# *   `string[start, length]`.
-# *   `string[range]`.
-# *   `string[regexp, capture = 0]`.
-# *   `string[substring]`.
+# The arguments have several forms. For a string `string`, the forms are:
 #
+# *   `string[index]`
+# *   `string[start, length]`
+# *   `string[range]`
+# *   `string[regexp, capture = 0]`
+# *   `string[substring]`
 #
 # **`string[index]`**
 #
-# When non-negative integer argument `index` is given, the slice is the
+# When a non-negative integer argument `index` is given, the slice is the
 # 1-character substring found in `self` at character offset `index`:
 #
-#     'bar'[0]       # => "b"
-#     'bar'[2]       # => "r"
-#     'bar'[20]      # => nil
-#     'тест'[2]      # => "с"
-#     'こんにちは'[4]  # => "は"
+#     'bar'[0]      # => "b"
+#     'bar'[2]      # => "r"
+#     'bar'[20]     # => nil
+#     'тест'[2]     # => "с"
+#     'こんにちは'[4] # => "は"
 #
-# When negative integer `index` is given, the slice begins at the offset given
+# When a negative integer `index` is given, the slice begins at the offset given
 # by counting backward from the end of `self`:
 #
-#     'bar'[-3]         # => "b"
-#     'bar'[-1]         # => "r"
-#     'bar'[-20]        # => nil
+#     'bar'[-3]      # => "b"
+#     'bar'[-1]      # => "r"
+#     'bar'[-20]     # => nil
 #
 # **`string[start, length]`**
 #
@@ -207,105 +197,104 @@
 # begins at character offset `start`, if it exists, and continues for `length`
 # characters, if available:
 #
-#     'foo'[0, 2]       # => "fo"
-#     'тест'[1, 2]      # => "ес"
-#     'こんにちは'[2, 2]  # => "にち"
+#     'foo'[0, 2]      # => "fo"
+#     'тест'[1, 2]     # => "ес"
+#     'こんにちは'[2, 2] # => "にち"
 #     # Zero length.
-#     'foo'[2, 0]       # => ""
+#     'foo'[2, 0]      # => ""
 #     # Length not entirely available.
-#     'foo'[1, 200]     # => "oo"
+#     'foo'[1, 200]    # => "oo"
 #     # Start out of range.
 #     'foo'[4, 2]      # => nil
 #
-# Special case: if `start` is equal to the length of `self`, the slice is a new
-# empty string:
+# Special case: if `start` equals the length of `self`, the slice is a new empty
+# string:
 #
-#     'foo'[3, 2]   # => ""
-#     'foo'[3, 200] # => ""
+#     'foo'[3, 2]    # => ""
+#     'foo'[3, 200]  # => ""
 #
-# When negative `start` and non-negative `length` are given, the slice beginning
-# is determined by counting backward from the end of `self`, and the slice
-# continues for `length` characters, if available:
+# When a negative `start` and non-negative `length` are given, the slice begins
+# by counting backward from the end of `self`, and continues for `length`
+# characters, if available:
 #
-#     'foo'[-2, 2]    # => "oo"
-#     'foo'[-2, 200]  # => "oo"
+#     'foo'[-2, 2]     # => "oo"
+#     'foo'[-2, 200]   # => "oo"
 #     # Start out of range.
 #     'foo'[-4, 2]     # => nil
 #
-# When negative `length` is given, there is no slice:
+# When a negative `length` is given, there is no slice:
 #
-#     'foo'[1, -1]  # => nil
-#     'foo'[-2, -1] # => nil
+#     'foo'[1, -1]   # => nil
+#     'foo'[-2, -1]  # => nil
 #
 # **`string[range]`**
 #
-# When Range argument `range` is given, creates a substring of `string` using
-# the indices in `range`. The slice is then determined as above:
+# When a Range argument `range` is given, it creates a substring of `string`
+# using the indices in `range`. The slice is then determined as above:
 #
-#     'foo'[0..1]    # => "fo"
-#     'foo'[0, 2]    # => "fo"
+#     'foo'[0..1]     # => "fo"
+#     'foo'[0, 2]     # => "fo"
 #
-#     'foo'[2...2]   # => ""
-#     'foo'[2, 0]    # => ""
+#     'foo'[2...2]    # => ""
+#     'foo'[2, 0]     # => ""
 #
-#     'foo'[1..200]  # => "oo"
-#     'foo'[1, 200]  # => "oo"
+#     'foo'[1..200]   # => "oo"
+#     'foo'[1, 200]   # => "oo"
 #
-#     'foo'[4..5]    # => nil
-#     'foo'[4, 2]    # => nil
+#     'foo'[4..5]     # => nil
+#     'foo'[4, 2]     # => nil
 #
-#     'foo'[-4..-3]  # => nil
-#     'foo'[-4, 2]   # => nil
+#     'foo'[-4..-3]   # => nil
+#     'foo'[-4, 2]    # => nil
 #
-#     'foo'[3..4]    # => ""
-#     'foo'[3, 2]    # => ""
+#     'foo'[3..4]     # => ""
+#     'foo'[3, 2]     # => ""
 #
-#     'foo'[-2..-1]  # => "oo"
-#     'foo'[-2, 2]   # => "oo"
+#     'foo'[-2..-1]   # => "oo"
+#     'foo'[-2, 2]    # => "oo"
 #
-#     'foo'[-2..197] # => "oo"
-#     'foo'[-2, 200] # => "oo"
+#     'foo'[-2..197]  # => "oo"
+#     'foo'[-2, 200]  # => "oo"
 #
 # **`string[regexp, capture = 0]`**
 #
 # When the Regexp argument `regexp` is given, and the `capture` argument is `0`,
 # the slice is the first matching substring found in `self`:
 #
-#     'foo'[/o/] # => "o"
-#     'foo'[/x/] # => nil
+#     'foo'[/o/]                # => "o"
+#     'foo'[/x/]                # => nil
 #     s = 'hello there'
-#     s[/[aeiou](.)\1/] # => "ell"
-#     s[/[aeiou](.)\1/, 0] # => "ell"
+#     s[/[aeiou](.)\1/]        # => "ell"
+#     s[/[aeiou](.)\1/, 0]     # => "ell"
 #
-# 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@Groups+and+Captures):
+# If the argument `capture` is provided and not `0`, it should be either a
+# capture group index (integer) or a capture group name (String or Symbol); the
+# slice is the specified capture (see Regexp@Groups and Captures):
 #
 #     s = 'hello there'
 #     s[/[aeiou](.)\1/, 1] # => "l"
 #     s[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, "non_vowel"] # => "l"
-#     s[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, :vowel] # => "e"
+#     s[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, :vowel]      # => "e"
 #
 # If an invalid capture group index is given, there is no slice. If an invalid
 # capture group name is given, `IndexError` is raised.
 #
 # **`string[substring]`**
 #
-# When the single String argument `substring` is given, returns the substring
-# from `self` if found, otherwise `nil`:
+# When the single `String` argument `substring` is given, it returns the
+# substring from `self` if found, otherwise `nil`:
 #
 #     'foo'['oo'] # => "oo"
 #     'foo'['xx'] # => nil
 #
 # ## What's Here
 #
-# First, what's elsewhere. Class String:
-#
-# *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
-# *   Includes [module Comparable](rdoc-ref:Comparable@What-27s+Here).
+# First, what's elsewhere. Class `String`:
 #
+# *   Inherits from the [Object class](rdoc-ref:Object@What-27s+Here).
+# *   Includes the [Comparable module](rdoc-ref:Comparable@What-27s+Here).
 #
-# Here, class String provides methods that are useful for:
+# Here, class `String` provides methods that are useful for:
 #
 # *   [Creating a String](rdoc-ref:String@Methods+for+Creating+a+String)
 # *   [Frozen/Unfrozen
@@ -316,35 +305,31 @@
 # *   [Converting to New
 #     String](rdoc-ref:String@Methods+for+Converting+to+New+String)
 # *   [Converting to
-#     Non-String](rdoc-ref:String@Methods+for+Converting+to+Non--5CString)
+#     Non-String](rdoc-ref:String@Methods+for+Converting+to+Non-String)
 # *   [Iterating](rdoc-ref:String@Methods+for+Iterating)
 #
-#
-# ### Methods for Creating a String
+# ### Methods for Creating a `String`
 #
 # *   ::new: Returns a new string.
 # *   ::try_convert: Returns a new string created from a given object.
 #
-#
 # ### Methods for a Frozen/Unfrozen String
 #
-# *   #+@: Returns a string that is not frozen: `self`, if not frozen;
-#     `self.dup` otherwise.
-# *   #-@: Returns a string that is frozen: `self`, if already frozen;
-#     `self.freeze` otherwise.
-# *   #freeze: Freezes `self`, if not already frozen; returns `self`.
-#
+# *   #+@: Returns a string that is not frozen: `self` if not frozen; `self.dup`
+#     otherwise.
+# *   #-@ (aliased as #dedup): Returns a string that is frozen: `self` if
+#     already frozen; `self.freeze` otherwise.
+# *   #freeze: Freezes `self` if not already frozen; returns `self`.
 #
 # ### Methods for Querying
 #
 # *Counts*
 #
-# *   #length, #size: Returns the count of characters (not bytes).
+# *   #length (aliased as #size): Returns the count of characters (not bytes).
 # *   #empty?: Returns `true` if `self.length` is zero; `false` otherwise.
 # *   #bytesize: Returns the count of bytes.
 # *   #count: Returns the count of substrings matching given strings.
 #
-#
 # *Substrings*
 #
 # *   #=~: Returns the index of the first substring that matches a given Regexp
@@ -364,7 +349,6 @@
 # *   #end_with?: Returns `true` if the string ends with any of the given
 #     substrings.
 #
-#
 # *Encodings*
 #
 # *   #encoding: Returns the Encoding object that represents the encoding of the
@@ -376,17 +360,15 @@
 # *   #ascii_only?: Returns `true` if the string has only ASCII characters;
 #     `false` otherwise.
 #
-#
 # *Other*
 #
 # *   #sum: Returns a basic checksum for the string: the sum of each byte.
 # *   #hash: Returns the integer hash code.
 #
-#
 # ### Methods for Comparing
 #
-# *   #==, #===: Returns `true` if a given other string has the same content as
-#     `self`.
+# *   #== (aliased as #===): Returns `true` if a given other string has the same
+#     content as `self`.
 # *   #eql?: Returns `true` if the content is the same as the given other
 #     string.
 # *   #<=>: Returns -1, 0, or 1 as a given other string is smaller than, equal
@@ -396,16 +378,17 @@
 # *   #casecmp?: Returns `true` if the string is equal to a given string after
 #     Unicode case folding; `false` otherwise.
 #
-#
-# ### Methods for Modifying a String
+# ### Methods for Modifying a `String`
 #
 # Each of these methods modifies `self`.
 #
 # *Insertion*
 #
-# *   #insert: Returns `self` with a given string inserted at a given offset.
+# *   #insert: Returns `self` with a given string inserted at a specified
+#     offset.
 # *   #<<: Returns `self` concatenated with a given string or integer.
-#
+# *   #append_as_bytes: Returns `self` concatenated with strings without
+#     performing any encoding validation or conversion.
 #
 # *Substitution*
 #
@@ -413,9 +396,10 @@
 #     given replacement string; returns `self` if any changes, `nil` otherwise.
 # *   #gsub!: Replaces each substring that matches a given pattern with a given
 #     replacement string; returns `self` if any changes, `nil` otherwise.
-# *   #succ!, #next!: Returns `self` modified to become its own successor.
-# *   #replace: Returns `self` with its entire content replaced by a given
-#     string.
+# *   #succ! (aliased as #next!): Returns `self` modified to become its own
+#     successor.
+# *   #initialize_copy (aliased as #replace): Returns `self` with its entire
+#     content replaced by a given string.
 # *   #reverse!: Returns `self` with its characters in reverse order.
 # *   #setbyte: Sets the byte at a given integer offset to a given value;
 #     returns the argument.
@@ -425,7 +409,6 @@
 #     characters, removing duplicates from the substrings that were modified;
 #     returns `self` if any changes, `nil` otherwise.
 #
-#
 # *Casing*
 #
 # *   #capitalize!: Upcases the initial character and downcases all others;
@@ -437,17 +420,15 @@
 # *   #swapcase!: Upcases each downcase character and downcases each upcase
 #     character; returns `self` if any changes, `nil` otherwise.
 #
-#
 # *Encoding*
 #
-# *   #encode!: Returns `self` with all characters transcoded from one given
-#     encoding into another.
+# *   #encode!: Returns `self` with all characters transcoded from one encoding
+#     to another.
 # *   #unicode_normalize!: Unicode-normalizes `self`; returns `self`.
 # *   #scrub!: Replaces each invalid byte with a given character; returns
 #     `self`.
 # *   #force_encoding: Changes the encoding to a given encoding; returns `self`.
 #
-#
 # *Deletion*
 #
 # *   #clear: Removes all content, so that `self` is empty; returns `self`.
@@ -462,22 +443,21 @@
 #     `nil` otherwise.
 # *   #strip!: Removes leading and trailing whitespace; returns `self` if any
 #     changes, `nil` otherwise.
-# *   #chomp!: Removes trailing record separator, if found; returns `self` if
-#     any changes, `nil` otherwise.
+# *   #chomp!: Removes the trailing record separator, if found; returns `self`
+#     if any changes, `nil` otherwise.
 # *   #chop!: Removes trailing newline characters if found; otherwise removes
 #     the last character; returns `self` if any changes, `nil` otherwise.
 #
+# ### Methods for Converting to New `String`
 #
-# ### Methods for Converting to New String
-#
-# Each of these methods returns a new String based on `self`, often just a
+# Each of these methods returns a new `String` based on `self`, often just a
 # modified copy of `self`.
 #
 # *Extension*
 #
-# *   #*: Returns the concatenation of multiple copies of `self`,
+# *   #*: Returns the concatenation of multiple copies of `self`.
 # *   #+: Returns the concatenation of `self` and a given other string.
-# *   #center: Returns a copy of `self` centered between pad substring.
+# *   #center: Returns a copy of `self` centered between pad substrings.
 # *   #concat: Returns the concatenation of `self` with given other strings.
 # *   #prepend: Returns the concatenation of a given other string with `self`.
 # *   #ljust: Returns a copy of `self` of a given length, right-padded with a
@@ -485,7 +465,6 @@
 # *   #rjust: Returns a copy of `self` of a given length, left-padded with a
 #     given other string.
 #
-#
 # *Encoding*
 #
 # *   #b: Returns a copy of `self` with ASCII-8BIT encoding.
@@ -494,29 +473,28 @@
 # *   #unicode_normalize: Returns a copy of `self` with each character
 #     Unicode-normalized.
 # *   #encode: Returns a copy of `self` with all characters transcoded from one
-#     given encoding into another.
-#
+#     encoding to another.
 #
 # *Substitution*
 #
 # *   #dump: Returns a copy of `self` with all non-printing characters replaced
 #     by xHH notation and all special characters escaped.
-# *   #undump: Returns a copy of `self` with all `\xNN` notation replace by
-#     `\uNNNN` notation and all escaped characters unescaped.
+# *   #undump: Returns a copy of `self` with all `\xNN` notations replaced by
+#     `\uNNNN` notations and all escaped characters unescaped.
 # *   #sub: Returns a copy of `self` with the first substring matching a given
-#     pattern replaced with a given replacement string;.
+#     pattern replaced with a given replacement string.
 # *   #gsub: Returns a copy of `self` with each substring that matches a given
 #     pattern replaced with a given replacement string.
-# *   #succ, #next: Returns the string that is the successor to `self`.
+# *   #succ (aliased as #next): Returns the string that is the successor to
+#     `self`.
 # *   #reverse: Returns a copy of `self` with its characters in reverse order.
 # *   #tr: Returns a copy of `self` with specified characters replaced with
-#     specified      replacement characters.
+#     specified replacement characters.
 # *   #tr_s: Returns a copy of `self` with specified characters replaced with
 #     specified replacement characters, removing duplicates from the substrings
 #     that were modified.
 # *   #%: Returns the string resulting from formatting a given object into
-#     `self`
-#
+#     `self`.
 #
 # *Casing*
 #
@@ -527,10 +505,9 @@
 # *   #swapcase: Returns a copy of `self` with all upcase characters downcased
 #     and all downcase characters upcased.
 #
-#
 # *Deletion*
 #
-# *   #delete: Returns a copy of `self` with characters removed
+# *   #delete: Returns a copy of `self` with characters removed.
 # *   #delete_prefix: Returns a copy of `self` with a given prefix removed.
 # *   #delete_suffix: Returns a copy of `self` with a given suffix removed.
 # *   #lstrip: Returns a copy of `self` with leading whitespace removed.
@@ -543,55 +520,50 @@
 #     last character removed.
 # *   #squeeze: Returns a copy of `self` with contiguous duplicate characters
 #     removed.
-# *   #[], #slice: Returns a substring determined by a given index,
-#     start/length, or range, or string.
+# *   #[] (aliased as #slice): Returns a substring determined by a given index,
+#     start/length, range, regexp, or string.
 # *   #byteslice: Returns a substring determined by a given index, start/length,
 #     or range.
 # *   #chr: Returns the first character.
 #
-#
 # *Duplication*
 #
-# *   #to_s, $to_str: If `self` is a subclass of String, returns `self` copied
-#     into a String; otherwise, returns `self`.
+# *   #to_s (aliased as #to_str): If `self` is a subclass of `String`, returns
+#     `self` copied into a `String`; otherwise, returns `self`.
 #
+# ### Methods for Converting to Non-`String`
 #
-# ### Methods for Converting to Non-String
-#
-# Each of these methods converts the contents of `self` to a non-String.
+# Each of these methods converts the contents of `self` to a non-`String`.
 #
 # *Characters, Bytes, and Clusters*
 #
 # *   #bytes: Returns an array of the bytes in `self`.
 # *   #chars: Returns an array of the characters in `self`.
 # *   #codepoints: Returns an array of the integer ordinals in `self`.
-# *   #getbyte: Returns an integer byte as determined by a given index.
+# *   #getbyte: Returns the integer byte at the given index in `self`.
 # *   #grapheme_clusters: Returns an array of the grapheme clusters in `self`.
 #
-#
 # *Splitting*
 #
 # *   #lines: Returns an array of the lines in `self`, as determined by a given
 #     record separator.
 # *   #partition: Returns a 3-element array determined by the first substring
-#     that matches a given substring or regexp,
+#     that matches a given substring or regexp.
 # *   #rpartition: Returns a 3-element array determined by the last substring
-#     that matches a given substring or regexp,
+#     that matches a given substring or regexp.
 # *   #split: Returns an array of substrings determined by a given delimiter --
-#     regexp or string -- or, if a block given, passes those substrings to the
-#     block.
-#
+#     regexp or string -- or, if a block is given, passes those substrings to
+#     the block.
 #
 # *Matching*
 #
 # *   #scan: Returns an array of substrings matching a given regexp or string,
-#     or, if a block given, passes each matching substring to the  block.
+#     or, if a block is given, passes each matching substring to the block.
 # *   #unpack: Returns an array of substrings extracted from `self` according to
 #     a given format.
 # *   #unpack1: Returns the first substring extracted from `self` according to a
 #     given format.
 #
-#
 # *Numerics*
 #
 # *   #hex: Returns the integer value of the leading characters, interpreted as
@@ -604,13 +576,11 @@
 # *   #to_f: Returns the floating-point value of leading characters, interpreted
 #     as a floating-point number.
 #
-#
 # *Strings and Symbols*
 #
-# *   #inspect: Returns copy of `self`, enclosed in double-quotes, with special
-#     characters escaped.
-# *   #to_sym, #intern: Returns the symbol corresponding to `self`.
-#
+# *   #inspect: Returns a copy of `self`, enclosed in double quotes, with
+#     special characters escaped.
+# *   #intern (aliased as #to_sym): Returns the symbol corresponding to `self`.
 #
 # ### Methods for Iterating
 #
@@ -636,14 +606,14 @@ class String
   #   rdoc-file=string.c
   #   - String.try_convert(object) -> object, new_string, or nil
   # -->
-  # If `object` is a String object, returns `object`.
+  # If `object` is a `String` object, returns `object`.
   #
   # Otherwise if `object` responds to `:to_str`, calls `object.to_str` and returns
   # the result.
   #
   # Returns `nil` if `object` does not respond to `:to_str`.
   #
-  # Raises an exception unless `object.to_str` returns a String object.
+  # Raises an exception unless `object.to_str` returns a `String` object.
   #
   def self.try_convert: (String object) -> String # technically will return `object` unchanged.
                       | (_ToStr object) -> String
@@ -744,7 +714,7 @@ class String
   #   rdoc-file=string.c
   #   - string * integer -> new_string
   # -->
-  # Returns a new String containing `integer` copies of `self`:
+  # Returns a new `String` containing `integer` copies of `self`:
   #
   #     "Ho! " * 3 # => "Ho! Ho! Ho! "
   #     "Ho! " * 0 # => ""
@@ -755,7 +725,7 @@ class String
   #   rdoc-file=string.c
   #   - string + other_string -> new_string
   # -->
-  # Returns a new String containing `other_string` concatenated to `self`:
+  # Returns a new `String` containing `other_string` concatenated to `self`:
   #
   #     "Hello from " + self.to_s # => "Hello from main"
   #
@@ -765,7 +735,8 @@ class String
   #   rdoc-file=string.c
   #   - +string -> new_string or self
   # -->
-  # Returns `self` if `self` is not frozen.
+  # Returns `self` if `self` is not frozen and can be mutated without warning
+  # issuance.
   #
   # Otherwise returns `self.dup`, which is not frozen.
   #
@@ -778,7 +749,7 @@ class 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
+  # 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.
   #
   # Note that `-string` variant is more convenient for defining constants:
@@ -808,6 +779,22 @@ class String
   #     s = 'foo'
   #     s << 33 # => "foo!"
   #
+  # If that codepoint is not representable in the encoding of *string*, RangeError
+  # is raised.
+  #
+  #     s = 'foo'
+  #     s.encoding              # => <Encoding:UTF-8>
+  #     s << 0x00110000         # 1114112 out of char range (RangeError)
+  #     s = 'foo'.encode('EUC-JP')
+  #     s << 0x00800080         # invalid codepoint 0x800080 in EUC-JP (RangeError)
+  #
+  # If the encoding is US-ASCII and the codepoint is 0..0xff, *string* is
+  # automatically promoted to ASCII-8BIT.
+  #
+  #     s = 'foo'.encode('US-ASCII')
+  #     s << 0xff
+  #     s.encoding              # => #<Encoding:BINARY (ASCII-8BIT)>
+  #
   # Related: String#concat, which takes multiple arguments.
   #
   def <<: (string | Integer str_or_codepoint) -> self
@@ -823,7 +810,6 @@ class String
   # *   1 if `other_string` is smaller.
   # *   `nil` if the two are incomparable.
   #
-  #
   # Examples:
   #
   #     'foo' <=> 'foo' # => 0
@@ -852,7 +838,7 @@ class String
   # Returns `false` if the two strings' encodings are not compatible:
   #     "\u{e4 f6 fc}".encode("ISO-8859-1") == ("\u{c4 d6 dc}") # => false
   #
-  # If `object` is not an instance of String but responds to `to_str`, then the
+  # If `object` is not an instance of `String` but responds to `to_str`, then the
   # two strings are compared using `object.==`.
   #
   def ==: (untyped other) -> bool
@@ -869,7 +855,7 @@ class String
   # Returns `false` if the two strings' encodings are not compatible:
   #     "\u{e4 f6 fc}".encode("ISO-8859-1") == ("\u{c4 d6 dc}") # => false
   #
-  # If `object` is not an instance of String but responds to `to_str`, then the
+  # If `object` is not an instance of `String` but responds to `to_str`, then the
   # two strings are compared using `object.==`.
   #
   alias === ==
@@ -955,6 +941,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
@@ -1067,13 +1077,12 @@ class String
   #     $~ #=> #<MatchData "oo">
   #
   # Integer argument `offset`, if given and non-negative, specifies the maximum
-  # starting byte-based position in the
-  #     string to _end_ the search:
+  # starting byte-based position in the string to *end* the search:
   #
-  #      'foo'.byterindex('o', 0) # => nil
-  #      'foo'.byterindex('o', 1) # => 1
-  #      'foo'.byterindex('o', 2) # => 2
-  #      'foo'.byterindex('o', 3) # => 2
+  #     'foo'.byterindex('o', 0) # => nil
+  #     'foo'.byterindex('o', 1) # => 1
+  #     'foo'.byterindex('o', 2) # => 2
+  #     'foo'.byterindex('o', 3) # => 2
   #
   # If `offset` is a negative Integer, the maximum starting position in the string
   # to *end* the search is the sum of the string's length and `offset`:
@@ -1246,7 +1255,6 @@ class String
   # *   1 if `other_string.downcase` is smaller.
   # *   `nil` if the two are incomparable.
   #
-  #
   # Examples:
   #
   #     'foo'.casecmp('foo') # => 0
@@ -1522,7 +1530,6 @@ class String
   #             "foo".crypt("$5$rounds=1000$salt$") # OK, proper usage
   #             "foo".crypt("$5$round=1000$salt$")  # Typo not detected
   #
-  #
   # *   Even in the "modular" mode, some hash functions are considered archaic and
   #     no longer recommended at all; for instance module `$1$` is officially
   #     abandoned by its author: see http://phk.freebsd.dk/sagas/md5crypt_eol/ .
@@ -1536,7 +1543,6 @@ class String
   #
   #         "foo".crypt("$5$rounds=1000$salt$") # => "$5fNPQMxC5j6."
   #
-  #
   # If for some reason you cannot migrate to other secure contemporary password
   # hashing algorithms, install the string-crypt gem and `require 'string/crypt'`
   # to continue using it.
@@ -1546,7 +1552,7 @@ class String
   # <!-- rdoc-file=string.c -->
   # Returns a frozen, possibly pre-existing copy of the string.
   #
-  # The returned String will be deduplicated as long as it does not have any
+  # 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.
   #
   # Note that `-string` variant is more convenient for defining constants:
@@ -1894,7 +1900,6 @@ class String
   #         t = s.encode              # => "Ruby™"
   #         t.encoding                # => #<Encoding:UTF-8>
   #
-  #
   # With only argument `dst_encoding` given, uses that encoding:
   #
   #     s = "Ruby\x99".force_encoding('Windows-1252')
@@ -2135,7 +2140,7 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - include? other_string -> true or false
+  #   - include?(other_string) -> true or false
   # -->
   # Returns `true` if `self` contains `other_string`, `false` otherwise:
   #
@@ -2227,7 +2232,7 @@ class String
   #   - str.intern   -> symbol
   #   - str.to_sym   -> symbol
   # -->
-  # Returns the Symbol corresponding to *str*, creating the symbol if it did not
+  # Returns the `Symbol` corresponding to *str*, creating the symbol if it did not
   # previously exist. See Symbol#id2name.
   #
   #     "Koala".intern         #=> :Koala
@@ -2339,7 +2344,6 @@ class String
   #     (see Regexp#match):
   #         matchdata = <tt>regexp.match(self)
   #
-  #
   # With no block given, returns the computed `matchdata`:
   #
   #     'foo'.match('f') # => #<MatchData "f">
@@ -2434,7 +2438,7 @@ class String
   #     s = '99zz99zz'
   #     s.succ # => "100aa00aa"
   #
-  # The successor to an empty String is a new empty String:
+  # The successor to an empty `String` is a new empty `String`:
   #
   #     ''.succ # => ""
   #
@@ -2488,7 +2492,6 @@ class String
   # *   `string_or_regexp` itself, if it is a Regexp.
   # *   `Regexp.quote(string_or_regexp)`, if `string_or_regexp` is a string.
   #
-  #
   # If the pattern is matched, returns pre-match, first-match, post-match:
   #
   #     'hello'.partition('l')      # => ["he", "l", "lo"]
@@ -2590,13 +2593,12 @@ class String
   #     $~ #=> #<MatchData "oo">
   #
   # Integer argument `offset`, if given and non-negative, specifies the maximum
-  # starting position in the
-  #     string to _end_ the search:
+  # starting position in the string to *end* the search:
   #
-  #      'foo'.rindex('o', 0) # => nil
-  #      'foo'.rindex('o', 1) # => 1
-  #      'foo'.rindex('o', 2) # => 2
-  #      'foo'.rindex('o', 3) # => 2
+  #     'foo'.rindex('o', 0) # => nil
+  #     'foo'.rindex('o', 1) # => 1
+  #     'foo'.rindex('o', 2) # => 2
+  #     'foo'.rindex('o', 3) # => 2
   #
   # If `offset` is a negative Integer, the maximum starting position in the string
   # to *end* the search is the sum of the string's length and `offset`:
@@ -2647,7 +2649,6 @@ class String
   # *   `string_or_regexp` itself, if it is a Regexp.
   # *   `Regexp.quote(string_or_regexp)`, if `string_or_regexp` is a string.
   #
-  #
   # If the pattern is matched, returns pre-match, last-match, post-match:
   #
   #     'hello'.rpartition('l')      # => ["hel", "l", "o"]
@@ -2704,7 +2705,6 @@ class String
   # *   `string_or_regexp` itself, if it is a Regexp.
   # *   `Regexp.quote(string_or_regexp)`, if `string_or_regexp` is a string.
   #
-  #
   # Iterates through `self`, generating a collection of matching results:
   #
   # *   If the pattern contains no groups, each result is the matched string,
@@ -2712,7 +2712,6 @@ class String
   # *   If the pattern contains groups, each result is an array containing one
   #     entry per group.
   #
-  #
   # With no block given, returns an array of the results:
   #
   #     s = 'cruel world'
@@ -2733,8 +2732,8 @@ class String
   #     <<cruel>> <<world>>
   #     rceu lowlr
   #
-  def scan: (Regexp pattern) -> Array[String | Array[String]]
-          | (Regexp pattern) { (String | Array[String] matches) -> void } -> self
+  def scan: (Regexp pattern) -> Array[String | Array[String?]]
+          | (Regexp pattern) { (String | Array[String?] matches) -> void } -> self
           | (string pattern) -> Array[String]
           | (string pattern) { (String match) -> void } -> self
 
@@ -2844,8 +2843,8 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - split(field_sep = $;, limit = nil) -> array
-  #   - split(field_sep = $;, limit = nil) {|substring| ... } -> self
+  #   - split(field_sep = $;, limit = 0) -> array
+  #   - split(field_sep = $;, limit = 0) {|substring| ... } -> self
   # -->
   # Returns an array of substrings of `self` that are the result of splitting
   # `self` at each occurrence of the given field separator `field_sep`.
@@ -2855,19 +2854,18 @@ class String
   # *   If `$;` is `nil` (its default value), the split occurs just as if
   #     `field_sep` were given as a space character (see below).
   #
-  # *   If `$;` is a string, the split ocurs just as if `field_sep` were given as
+  # *   If `$;` is a string, the split occurs just as if `field_sep` were given as
   #     that string (see below).
   #
-  #
-  # When `field_sep` is `' '` and `limit` is `nil`, the split occurs at each
-  # sequence of whitespace:
+  # When `field_sep` is `' '` and `limit` is `0` (its default value), the split
+  # occurs at each sequence of whitespace:
   #
   #     'abc def ghi'.split(' ')         => ["abc", "def", "ghi"]
   #     "abc \n\tdef\t\n  ghi".split(' ') # => ["abc", "def", "ghi"]
   #     'abc  def   ghi'.split(' ')      => ["abc", "def", "ghi"]
   #     ''.split(' ')                    => []
   #
-  # When `field_sep` is a string different from `' '` and `limit` is `nil`, the
+  # When `field_sep` is a string different from `' '` and `limit` is `0`, the
   # split occurs at each occurrence of `field_sep`; trailing empty substrings are
   # not returned:
   #
@@ -2879,7 +2877,7 @@ class String
   #     'тест'.split('т')          => ["", "ес"]
   #     'こんにちは'.split('に')     => ["こん", "ちは"]
   #
-  # When `field_sep` is a Regexp and `limit` is `nil`, the split occurs at each
+  # When `field_sep` is a Regexp and `limit` is `0`, the split occurs at each
   # occurrence of a match; trailing empty substrings are not returned:
   #
   #     'abracadabra'.split(/ab/) # => ["", "racad", "ra"]
@@ -2892,11 +2890,9 @@ class String
   #
   #     '1:2:3'.split(/(:)()()/, 2) # => ["1", ":", "", "", "2:3"]
   #
-  # As seen above, if `limit` is `nil`, trailing empty substrings are not
-  # returned; the same is true if `limit` is zero:
+  # As seen above, if `limit` is `0`, trailing empty substrings are not returned:
   #
   #     'aaabcdaaa'.split('a')   => ["", "", "", "bcd"]
-  #     'aaabcdaaa'.split('a', 0) # => ["", "", "", "bcd"]
   #
   # If `limit` is positive integer `n`, no more than `n - 1-` splits occur, so
   # that at most `n` substrings are returned, and trailing empty substrings are
@@ -2911,7 +2907,7 @@ class String
   # Note that if `field_sep` is a Regexp containing groups, their matches are in
   # the returned array, but do not count toward the limit.
   #
-  # If `limit` is negative, it behaves the same as if `limit` was `nil`, meaning
+  # If `limit` is negative, it behaves the same as if `limit` was zero, meaning
   # that there is no limit, and trailing empty substrings are included:
   #
   #     'aaabcdaaa'.split('a', -1) # => ["", "", "", "bcd", "", "", ""]
@@ -2970,7 +2966,6 @@ class String
   # *   `string_or_regexp` itself, if it is a Regexp.
   # *   `Regexp.quote(string_or_regexp)`, if `string_or_regexp` is a string.
   #
-  #
   # Returns `true` if any pattern matches the beginning, `false` otherwise:
   #
   #     'hello'.start_with?('hell')               # => true
@@ -3031,8 +3026,8 @@ class String
   #   - sub!(pattern, replacement)   -> self or nil
   #   - sub!(pattern) {|match| ... } -> self or nil
   # -->
-  # Returns `self` with only the first occurrence (not all occurrences) of the
-  # given `pattern` replaced.
+  # Replaces the first occurrence (not all occurrences) of the given `pattern` on
+  # `self`; returns `self` if a replacement occurred, `nil` otherwise.
   #
   # See [Substitution Methods](rdoc-ref:String@Substitution+Methods).
   #
@@ -3092,7 +3087,7 @@ class String
   #     s = '99zz99zz'
   #     s.succ # => "100aa00aa"
   #
-  # The successor to an empty String is a new empty String:
+  # The successor to an empty `String` is a new empty `String`:
   #
   #     ''.succ # => ""
   #
@@ -3278,19 +3273,19 @@ class String
   #   rdoc-file=string.c
   #   - to_s -> self or string
   # -->
-  # Returns `self` if `self` is a String, or `self` converted to a String if
-  # `self` is a subclass of String.
+  # Returns `self` if `self` is a `String`, or `self` converted to a `String` if
+  # `self` is a subclass of `String`.
   #
   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.
+  # Returns `self` if `self` is a `String`, or `self` converted to a `String` if
+  # `self` is a subclass of `String`.
   #
   alias to_str to_s
 
   # <!-- rdoc-file=string.c -->
-  # Returns the Symbol corresponding to *str*, creating the symbol if it did not
+  # Returns the `Symbol` corresponding to *str*, creating the symbol if it did not
   # previously exist. See Symbol#id2name.
   #
   #     "Koala".intern         #=> :Koala
@@ -3320,7 +3315,6 @@ class String
   #     translated to the second character in `replacements`.
   # *   And so on.
   #
-  #
   # Example:
   #
   #     'hello'.tr('el', 'ip') #=> "hippo"
@@ -3411,7 +3405,6 @@ class String
   # *   `:nfkc`: Compatibility decomposition, followed by canonical composition.
   # *   `:nfkd`: Compatibility decomposition.
   #
-  #
   # The encoding of `self` must be one of:
   #
   # *   Encoding::UTF_8
@@ -3423,7 +3416,6 @@ class String
   # *   Encoding::UCS_2BE
   # *   Encoding::UCS_4BE
   #
-  #
   # Examples:
   #
   #     "a\u0300".unicode_normalize      # => "a"
@@ -3470,10 +3462,14 @@ class String
 
   # <!--
   #   rdoc-file=pack.rb
-  #   - unpack(template, offset: 0) -> array
+  #   - unpack(template, offset: 0, &block) -> array
   # -->
-  # 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).
+  # Extracts data from `self`.
+  #
+  # If `block` is not given, forming objects that become the elements of a new
+  # array, and returns that array.  Otherwise, yields each object.
+  #
+  # See [Packed Data](rdoc-ref:packed_data.rdoc).
   #
   def unpack: (string template, ?offset: int) -> Array[Integer | Float | String | nil]
             | (string template, ?offset: int) { (Integer | Float | String | nil value) -> void } -> nil
@@ -3533,7 +3529,7 @@ class String
   #   - upto(other_string, exclusive = false) {|string| ... } -> self
   #   - upto(other_string, exclusive = false) -> new_enumerator
   # -->
-  # With a block given, calls the block with each String value returned by
+  # With a block given, calls the block with each `String` value returned by
   # successive calls to String#succ; the first value is `self`, the next is
   # `self.succ`, and so on; the sequence terminates when value `other_string` is
   # reached; returns `self`: