rbs 3.7.0 → 3.8.0.pre.1

data/core/string.rbs

@@ -1,23 +1,21 @@
 # <!-- 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
+# 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.
 #
@@ -30,10 +28,11 @@
 # 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:
 #
@@ -46,8 +45,6 @@
 #         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.
 #
@@ -68,19 +65,18 @@
 #
 #     '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.
 #
 # 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`.
 # *   `\k<name>` refers to the named capture `name`.
 #
-#
 # See Regexp for details.
 #
 # Note that within the string `replacement`, a character combination such as
@@ -94,7 +90,6 @@
 # *   `\`` corresponds to `$``, which contains string before match.
 # *   `\+` corresponds to `$+`, which contains last capture group.
 #
-#
 # See Regexp for details.
 #
 # Note that `\\\` is interpreted as an escape, i.e., a single backslash.
@@ -140,7 +135,7 @@
 #
 # ## Whitespace in Strings
 #
-# In class String, *whitespace* is defined as a contiguous sequence of
+# In class `String`, *whitespace* is defined as a contiguous sequence of
 # characters consisting of any mixture of the following:
 #
 # *   NL (null): `"\x00"`, `"\u0000"`.
@@ -151,25 +146,21 @@
 # *   CR (carriage return): `"\x0d"`, `"\r"`.
 # *   SP (space): `"\x20"`, `" "`.
 #
-#
 # Whitespace is relevant for these methods:
 #
 # *   #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.
 #
 # 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.
-#
+# *   String#[] (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.
 #
 # Each of the above methods takes arguments that determine the slice to be
 # copied or replaced.
@@ -182,7 +173,6 @@
 # *   `string[regexp, capture = 0]`.
 # *   `string[substring]`.
 #
-#
 # **`string[index]`**
 #
 # When non-negative integer argument `index` is given, the slice is the
@@ -291,7 +281,7 @@
 #
 # **`string[substring]`**
 #
-# When the single String argument `substring` is given, returns the substring
+# When the single `String` argument `substring` is given, returns the substring
 # from `self` if found, otherwise `nil`:
 #
 #     'foo'['oo'] # => "oo"
@@ -299,13 +289,12 @@
 #
 # ## What's Here
 #
-# First, what's elsewhere. Class String:
+# 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).
 #
-#
-# 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.
+# *   #-@ (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,8 +378,7 @@
 # *   #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`.
 #
@@ -405,7 +386,8 @@
 #
 # *   #insert: Returns `self` with a given string inserted at a given 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 +395,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 +408,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,7 +419,6 @@
 # *   #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
@@ -447,7 +428,6 @@
 #     `self`.
 # *   #force_encoding: Changes the encoding to a given encoding; returns `self`.
 #
-#
 # *Deletion*
 #
 # *   #clear: Removes all content, so that `self` is empty; returns `self`.
@@ -467,10 +447,9 @@
 # *   #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*
@@ -485,7 +464,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.
@@ -496,7 +474,6 @@
 # *   #encode: Returns a copy of `self` with all characters transcoded from one
 #     given encoding into another.
 #
-#
 # *Substitution*
 #
 # *   #dump: Returns a copy of `self` with all non-printing characters replaced
@@ -507,7 +484,8 @@
 #     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.
@@ -517,7 +495,6 @@
 # *   #%: Returns the string resulting from formatting a given object into
 #     `self`
 #
-#
 # *Casing*
 #
 # *   #capitalize: Returns a copy of `self` with the first character upcased and
@@ -527,7 +504,6 @@
 # *   #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
@@ -543,22 +519,20 @@
 #     last character removed.
 # *   #squeeze: Returns a copy of `self` with contiguous duplicate characters
 #     removed.
-# *   #[], #slice: Returns a substring determined by a given index,
+# *   #[] (aliased as #slice): Returns a substring determined by a given index,
 #     start/length, or range, 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*
 #
@@ -568,7 +542,6 @@
 # *   #getbyte: Returns an integer byte as determined by a given index.
 # *   #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
@@ -581,7 +554,6 @@
 #     regexp or string -- or, if a block given, passes those substrings to the
 #     block.
 #
-#
 # *Matching*
 #
 # *   #scan: Returns an array of substrings matching a given regexp or string,
@@ -591,7 +563,6 @@
 # *   #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 +575,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`.
-#
+# *   #intern (aliased as #to_sym): Returns the symbol corresponding to `self`.
 #
 # ### Methods for Iterating
 #
@@ -636,14 +605,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 +713,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 +724,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"
   #
@@ -778,7 +747,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 +777,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 +808,6 @@ class String
   # *   1 if `other_string` is smaller.
   # *   `nil` if the two are incomparable.
   #
-  #
   # Examples:
   #
   #     'foo' <=> 'foo' # => 0
@@ -852,7 +836,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 +853,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 +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
@@ -1067,13 +1075,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 +1253,6 @@ class String
   # *   1 if `other_string.downcase` is smaller.
   # *   `nil` if the two are incomparable.
   #
-  #
   # Examples:
   #
   #     'foo'.casecmp('foo') # => 0
@@ -1522,7 +1528,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 +1541,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 +1550,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 +1898,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 +2138,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 +2230,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 +2342,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 +2436,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 +2490,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 +2591,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 +2647,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 +2703,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 +2710,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 +2730,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 +2841,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 +2852,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 +2875,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 +2888,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 +2905,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 +2964,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 +3024,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 +3085,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 +3271,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 +3313,6 @@ class String
   #     translated to the second character in `replacements`.
   # *   And so on.
   #
-  #
   # Example:
   #
   #     'hello'.tr('el', 'ip') #=> "hippo"
@@ -3411,7 +3403,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 +3414,6 @@ class String
   # *   Encoding::UCS_2BE
   # *   Encoding::UCS_4BE
   #
-  #
   # Examples:
   #
   #     "a\u0300".unicode_normalize      # => "a"
@@ -3470,10 +3460,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 +3527,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`: