rbs 3.10.0.pre.2 → 3.10.0

data/core/string.rbs

@@ -187,10 +187,10 @@
 #
 # *Counts*
 #
-# *   #length (aliased as #size): Returns the count of characters (not bytes).
-# *   #empty?: Returns whether the length of `self` is zero.
 # *   #bytesize: Returns the count of bytes.
 # *   #count: Returns the count of substrings matching given strings.
+# *   #empty?: Returns whether the length of `self` is zero.
+# *   #length (aliased as #size): Returns the count of characters (not bytes).
 #
 # *Substrings*
 #
@@ -350,8 +350,8 @@
 # *Substitution*
 #
 # *   #dump: Returns a printable version of `self`, enclosed in double-quotes.
-# *   #undump: Returns a copy of `self` with all `\xNN` notations replaced by
-#     `\uNNNN` notations and all escaped characters unescaped.
+# *   #undump: Inverse of #dump; returns a copy of `self` with changes of the
+#     kinds made by #dump "undone."
 # *   #sub: Returns a copy of `self` with the first substring matching a given
 #     pattern replaced with a given replacement string.
 # *   #gsub: Returns a copy of `self` with each substring that matches a given
@@ -660,10 +660,10 @@
 #
 # *Counts*
 #
-# *   #length (aliased as #size): Returns the count of characters (not bytes).
-# *   #empty?: Returns whether the length of `self` is zero.
 # *   #bytesize: Returns the count of bytes.
 # *   #count: Returns the count of substrings matching given strings.
+# *   #empty?: Returns whether the length of `self` is zero.
+# *   #length (aliased as #size): Returns the count of characters (not bytes).
 #
 # *Substrings*
 #
@@ -823,8 +823,8 @@
 # *Substitution*
 #
 # *   #dump: Returns a printable version of `self`, enclosed in double-quotes.
-# *   #undump: Returns a copy of `self` with all `\xNN` notations replaced by
-#     `\uNNNN` notations and all escaped characters unescaped.
+# *   #undump: Inverse of #dump; returns a copy of `self` with changes of the
+#     kinds made by #dump "undone."
 # *   #sub: Returns a copy of `self` with the first substring matching a given
 #     pattern replaced with a given replacement string.
 # *   #gsub: Returns a copy of `self` with each substring that matches a given
@@ -1042,7 +1042,7 @@ class String
   # -->
   # Returns the result of formatting `object` into the format specifications
   # contained in `self` (see [Format
-  # Specifications](rdoc-ref:format_specifications.rdoc)):
+  # Specifications](rdoc-ref:language/format_specifications.rdoc)):
   #
   #     '%05d' % 123 # => "00123"
   #
@@ -1306,7 +1306,7 @@ class String
   #     'hello'[0]    # => "h"
   #     'hello'[4]    # => "o"
   #     'hello'[5]    # => nil
-  #     'тест'[2]     # => "с"
+  #     'Привет'[2]   # => "и"
   #     'こんにちは'[4] # => "は"
   #
   # With negative integer argument `index` given, counts backward from the end of
@@ -1387,7 +1387,7 @@ class String
   #     'hello'['ell']      # => "ell"
   #     'hello'['']         # => ""
   #     'hello'['nosuch']   # => nil
-  #     'тест'['ес']        # => "ес"
+  #     'Привет'['ив']      # => "ив"
   #     'こんにちは'['んにち'] # => "んにち"
   #
   # Related: see [Converting to New
@@ -1449,7 +1449,7 @@ class String
   # size `length` characters (as available) beginning at character offset
   # specified by `start`.
   #
-  # If argument `start` is non-negative, the offset is +start':
+  # If argument `start` is non-negative, the offset is `start`:
   #
   #     s = 'hello'
   #     s[0, 1] = 'foo'  # => "foo"
@@ -1989,23 +1989,30 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - capitalize(mapping = :ascii) -> string
+  #   - capitalize(mapping = :ascii) -> new_string
   # -->
   # Returns a string containing the characters in `self`, each with possibly
   # changed case:
   #
-  # *   The first character is upcased.
-  # *   All other characters are downcased.
+  # *   The first character made uppercase.
+  # *   All other characters are made lowercase.
   #
   # Examples:
   #
-  #     'hello world'.capitalize # => "Hello world"
-  #     'HELLO WORLD'.capitalize # => "Hello world"
+  #     'hello'.capitalize  # => "Hello"
+  #     'HELLO'.capitalize  # => "Hello"
+  #     'straße'.capitalize # => "Straße"  # Lowercase 'ß' not changed.
+  #     'STRAẞE'.capitalize # => "Straße"  # Uppercase 'ẞ' downcased to 'ß'.
+  #     'привет'.capitalize # => "Привет"
+  #     'ПРИВЕТ'.capitalize # => "Привет"
   #
-  # Some characters do not have upcase and downcase, and so are not changed; see
-  # [Case Mapping](rdoc-ref:case_mapping.rdoc):
+  # Some characters (and some character sets) do not have upcase and downcase
+  # versions; see [Case Mapping](rdoc-ref:case_mapping.rdoc):
   #
-  #     '1, 2, 3, ...'.capitalize # => "1, 2, 3, ..."
+  #     s = '1, 2, 3, ...'
+  #     s.capitalize == s # => true
+  #     s = 'こんにちは'
+  #     s.capitalize == s # => true
   #
   # The casing is affected by the given `mapping`, which may be `:ascii`, `:fold`,
   # or `:turkic`; see [Case Mappings](rdoc-ref:case_mapping.rdoc@Case+Mappings).
@@ -2631,18 +2638,25 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - downcase(mapping) -> string
+  #   - downcase(mapping = :ascii) -> new_string
   # -->
   # Returns a new string containing the downcased characters in `self`:
   #
-  #     'Hello, World!'.downcase      # => "hello, world!"
-  #     'ТЕСТ'.downcase               # => "тест"
-  #     'よろしくお願いします'.downcase # => "よろしくお願いします"
+  #     'HELLO'.downcase        # => "hello"
+  #     'STRAẞE'.downcase       # => "straße"
+  #     'ПРИВЕТ'.downcase       # => "привет"
+  #     'RubyGems.org'.downcase # => "rubygems.org"
+  #
+  # Some characters (and some character sets) do not have upcase and downcase
+  # versions; see [Case Mapping](rdoc-ref:case_mapping.rdoc):
   #
-  # Some characters do not have upcased and downcased versions.
+  #     s = '1, 2, 3, ...'
+  #     s.downcase == s # => true
+  #     s = 'こんにちは'
+  #     s.downcase == s # => true
   #
-  # The casing may be affected by the given `mapping`; see [Case
-  # Mapping](rdoc-ref:case_mapping.rdoc).
+  # The casing is affected by the given `mapping`, which may be `:ascii`, `:fold`,
+  # or `:turkic`; see [Case Mappings](rdoc-ref:case_mapping.rdoc@Case+Mappings).
   #
   # Related: see [Converting to New
   # String](rdoc-ref:String@Converting+to+New+String).
@@ -2672,60 +2686,104 @@ class String
   #   rdoc-file=string.c
   #   - dump -> new_string
   # -->
-  # Returns a printable version of `self`, enclosed in double-quotes:
+  # For an ordinary string, this method, +String#dump+, returns a printable
+  # ASCII-only version of `self`, enclosed in double-quotes.
+  #
+  # For a dumped string, method String#undump is the inverse of +String#dump+; it
+  # returns a "restored" version of `self`, where all the dumping changes have
+  # been undone.
+  #
+  # In the simplest case, the dumped string contains the original string, enclosed
+  # in double-quotes; this example is done in `irb` (interactive Ruby), which uses
+  # method `inspect` to render the results:
+  #
+  #     s = 'hello'   # => "hello"
+  #     s.dump        # => "\"hello\""
+  #     s.dump.undump # => "hello"
+  #
+  # Keep in mind that in the second line above:
+  #
+  # *   The outer double-quotes are put on by `inspect`, and *are* *not* part of
+  #     the output of #dump.
+  # *   The inner double-quotes *are* part of the output of `dump`, and are
+  #     escaped by `inspect` because they are within the outer double-quotes.
+  #
+  # To avoid confusion, we'll use this helper method to omit the outer
+  # double-quotes:
+  #
+  #     def dump(s)
+  #       print "String:   ", s, "\n"
+  #       print "Dumped:   ", s.dump, "\n"
+  #       print "Undumped: ", s.dump.undump, "\n"
+  #     end
   #
-  #     'hello'.dump     # => "\"hello\""
+  # So that for string `'hello'`, we'll see:
   #
-  # Certain special characters are rendered with escapes:
+  #     String:    hello
+  #     Dumped:    "hello"
+  #     Undumped:  hello
   #
-  #     '"'.dump  # => "\"\\\"\""
-  #     '\\'.dump # => "\"\\\\\""
+  # In a dump, certain special characters are escaped:
   #
-  # Non-printing characters are rendered with escapes:
+  #     String:    "
+  #     Dumped:    "\""
+  #     Undumped:  "
+  #
+  #     String:    \
+  #     Dumped:    "\\"
+  #     Undumped:  \
+  #
+  # In a dump, unprintable characters are replaced by printable ones; the
+  # unprintable characters are the whitespace characters (other than space
+  # itself); here we see the ordinals for those characers, together with
+  # explanatory text:
+  #
+  #     h = {
+  #        7 => 'Alert (BEL)',
+  #        8 => 'Backspace (BS)',
+  #        9 => 'Horizontal tab (HT)',
+  #       10 => 'Linefeed (LF)',
+  #       11 => 'Vertical tab (VT)',
+  #       12 => 'Formfeed (FF)',
+  #       13 => 'Carriage return (CR)'
+  #     }
+  #
+  # In this example, the dumped output is printed by method #inspect, and so
+  # contains both outer double-quotes and escaped inner double-quotes:
   #
   #     s = ''
-  #     s << 7   # Alarm (bell).
-  #     s << 8   # Back space.
-  #     s << 9   # Horizontal tab.
-  #     s << 10  # Line feed.
-  #     s << 11  # Vertical tab.
-  #     s << 12  # Form feed.
-  #     s << 13  # Carriage return.
-  #     s        # => "\a\b\t\n\v\f\r"
-  #     s.dump   # => "\"\\a\\b\\t\\n\\v\\f\\r\""
-  #
-  # If `self` is encoded in UTF-8 and contains Unicode characters, renders Unicode
-  # characters in Unicode escape sequence:
-  #
-  #     'тест'.dump     # => "\"\\u0442\\u0435\\u0441\\u0442\""
-  #     'こんにちは'.dump # => "\"\\u3053\\u3093\\u306B\\u3061\\u306F\""
-  #
-  # If the encoding of `self` is not ASCII-compatible (i.e.,
-  # `self.encoding.ascii_compatible?` returns `false`), renders all
-  # ASCII-compatible bytes as ASCII characters and all other bytes as hexadecimal.
-  # Appends `.dup.force_encoding(\"encoding\")`, where `<encoding>` is
-  # `self.encoding.name`:
+  #     h.keys.each {|i| s << i } # => [7, 8, 9, 10, 11, 12, 13]
+  #     s                         # => "\a\b\t\n\v\f\r"
+  #     s.dump                    # => "\"\\a\\b\\t\\n\\v\\f\\r\""
   #
-  #     s = 'hello'
-  #     s.encoding                # => #<Encoding:UTF-8>
-  #     s.dump                    # => "\"hello\""
-  #     s.encode('utf-16').dump   # => "\"\\xFE\\xFF\\x00h\\x00e\\x00l\\x00l\\x00o\".dup.force_encoding(\"UTF-16\")"
-  #     s.encode('utf-16le').dump # => "\"h\\x00e\\x00l\\x00l\\x00o\\x00\".dup.force_encoding(\"UTF-16LE\")"
+  # If `self` is encoded in UTF-8 and contains Unicode characters, each Unicode
+  # character is dumped as a Unicode escape sequence:
   #
-  #     s = 'тест'
-  #     s.encoding                # => #<Encoding:UTF-8>
-  #     s.dump                    # => "\"\\u0442\\u0435\\u0441\\u0442\""
-  #     s.encode('utf-16').dump   # => "\"\\xFE\\xFF\\x04B\\x045\\x04A\\x04B\".dup.force_encoding(\"UTF-16\")"
-  #     s.encode('utf-16le').dump # => "\"B\\x045\\x04A\\x04B\\x04\".dup.force_encoding(\"UTF-16LE\")"
+  #     String:    тест
+  #     Dumped:    "\u0442\u0435\u0441\u0442"
+  #     Undumped:  тест
   #
-  #     s = 'こんにちは'
-  #     s.encoding                # => #<Encoding:UTF-8>
-  #     s.dump                    # => "\"\\u3053\\u3093\\u306B\\u3061\\u306F\""
-  #     s.encode('utf-16').dump   # => "\"\\xFE\\xFF0S0\\x930k0a0o\".dup.force_encoding(\"UTF-16\")"
-  #     s.encode('utf-16le').dump # => "\"S0\\x930k0a0o0\".dup.force_encoding(\"UTF-16LE\")"
+  #     String:    こんにちは
+  #     Dumped:    "\u3053\u3093\u306B\u3061\u306F"
+  #     Undumped:  こんにちは
   #
-  # Related: see [Converting to New
-  # String](rdoc-ref:String@Converting+to+New+String).
+  # If the encoding of `self` is not ASCII-compatible (i.e., if
+  # `self.encoding.ascii_compatible?` returns `false`), each ASCII-compatible byte
+  # is dumped as an ASCII character, and all other bytes are dumped as
+  # hexadecimal; also appends `.dup.force_encoding(\"encoding\")`, where
+  # `<encoding>` is `self.encoding.name`:
+  #
+  #     String:    hello
+  #     Dumped:    "\xFE\xFF\x00h\x00e\x00l\x00l\x00o".dup.force_encoding("UTF-16")
+  #     Undumped:  hello
+  #
+  #     String:    тест
+  #     Dumped:    "\xFE\xFF\x04B\x045\x04A\x04B".dup.force_encoding("UTF-16")
+  #     Undumped:  тест
+  #
+  #     String:    こんにちは
+  #     Dumped:    "\xFE\xFF0S0\x930k0a0o".dup.force_encoding("UTF-16")
+  #     Undumped:  こんにちは
   #
   def dump: () -> String
 
@@ -3579,7 +3637,7 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - lstrip -> new_string
+  #   - lstrip(*selectors) -> new_string
   # -->
   # Returns a copy of `self` with leading whitespace removed; see [Whitespace in
   # Strings](rdoc-ref:String@Whitespace+in+Strings):
@@ -3590,6 +3648,19 @@ class String
   #     s.lstrip
   #     # => "abc\u0000\t\n\v\f\r "
   #
+  # If `selectors` are given, removes characters of `selectors` from the beginning
+  # of `self`:
+  #
+  #     s = "---abc+++"
+  #     s.lstrip("-") # => "abc+++"
+  #
+  # `selectors` must be valid character selectors (see [Character
+  # Selectors](rdoc-ref:character_selectors.rdoc)), and may use any of its valid
+  # forms, including negation, ranges, and escapes:
+  #
+  #     "01234abc56789".lstrip("0-9") # "abc56789"
+  #     "01234abc56789".lstrip("0-9", "^4-6") # "4abc56789"
+  #
   # Related: see [Converting to New
   # String](rdoc-ref:String@Converting+to+New+String).
   #
@@ -3597,7 +3668,7 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - lstrip! -> self or nil
+  #   - lstrip!(*selectors) -> self or nil
   # -->
   # Like String#lstrip, except that:
   #
@@ -3857,7 +3928,7 @@ class String
   #
   # If `pattern` is a Regexp, performs the equivalent of `self.match(pattern)`
   # (also setting [pattern-matching global
-  # variables](rdoc-ref:globals.md@Pattern+Matching)):
+  # variables](rdoc-ref:language/globals.md@Pattern+Matching)):
   #
   #     'hello'.partition(/h/)  # => ["", "h", "ello"]
   #     'hello'.partition(/l/)  # => ["he", "l", "lo"]
@@ -3871,7 +3942,7 @@ class String
   # If `pattern` is not a Regexp, converts it to a string (if it is not already
   # one), then performs the equivalent of `self.index(pattern)` (and does *not*
   # set [pattern-matching global
-  # variables](rdoc-ref:globals.md@Pattern+Matching)):
+  # variables](rdoc-ref:language/globals.md@Pattern+Matching)):
   #
   #     'hello'.partition('h')     # => ["", "h", "ello"]
   #     'hello'.partition('l')     # => ["he", "l", "lo"]
@@ -4062,7 +4133,7 @@ class String
   #
   # If `pattern` is a Regexp, searches for the last matching substring (also
   # setting [pattern-matching global
-  # variables](rdoc-ref:globals.md@Pattern+Matching)):
+  # variables](rdoc-ref:language/globals.md@Pattern+Matching)):
   #
   #     'hello'.rpartition(/l/)     # => ["hel", "l", "o"]
   #     'hello'.rpartition(/ll/)    # => ["he", "ll", "o"]
@@ -4075,7 +4146,8 @@ class String
   #
   # If `pattern` is not a Regexp, converts it to a string (if it is not already
   # one), then searches for the last matching substring (and does *not* set
-  # [pattern-matching global variables](rdoc-ref:globals.md@Pattern+Matching)):
+  # [pattern-matching global
+  # variables](rdoc-ref:language/globals.md@Pattern+Matching)):
   #
   #     'hello'.rpartition('l')     # => ["hel", "l", "o"]
   #     'hello'.rpartition('ll')    # => ["he", "ll", "o"]
@@ -4092,7 +4164,7 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - rstrip -> new_string
+  #   - rstrip(*selectors) -> new_string
   # -->
   # Returns a copy of `self` with trailing whitespace removed; see [Whitespace in
   # Strings](rdoc-ref:String@Whitespace+in+Strings):
@@ -4102,6 +4174,19 @@ class String
   #     s        # => "\u0000\t\n\v\f\r abc\u0000\t\n\v\f\r "
   #     s.rstrip # => "\u0000\t\n\v\f\r abc"
   #
+  # If `selectors` are given, removes characters of `selectors` from the end of
+  # `self`:
+  #
+  #     s = "---abc+++"
+  #     s.rstrip("+") # => "---abc"
+  #
+  # `selectors` must be valid character selectors (see [Character
+  # Selectors](rdoc-ref:character_selectors.rdoc)), and may use any of its valid
+  # forms, including negation, ranges, and escapes:
+  #
+  #     "01234abc56789".rstrip("0-9") # "01234abc"
+  #     "01234abc56789".rstrip("0-9", "^4-6") # "01234abc56"
+  #
   # Related: see [Converting to New
   # String](rdoc-ref:String@Converting+to+New+String).
   #
@@ -4109,7 +4194,7 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - rstrip! -> self or nil
+  #   - rstrip!(*selectors) -> self or nil
   # -->
   # Like String#rstrip, except that:
   #
@@ -4258,7 +4343,7 @@ class String
   #     'hello'[0]    # => "h"
   #     'hello'[4]    # => "o"
   #     'hello'[5]    # => nil
-  #     'тест'[2]     # => "с"
+  #     'Привет'[2]   # => "и"
   #     'こんにちは'[4] # => "は"
   #
   # With negative integer argument `index` given, counts backward from the end of
@@ -4339,7 +4424,7 @@ class String
   #     'hello'['ell']      # => "ell"
   #     'hello'['']         # => ""
   #     'hello'['nosuch']   # => nil
-  #     'тест'['ес']        # => "ес"
+  #     'Привет'['ив']      # => "ив"
   #     'こんにちは'['んにち'] # => "んにち"
   #
   # Related: see [Converting to New
@@ -4564,7 +4649,7 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - strip -> new_string
+  #   - strip(*selectors) -> new_string
   # -->
   # Returns a copy of `self` with leading and trailing whitespace removed; see
   # [Whitespace in Strings](rdoc-ref:String@Whitespace+in+Strings):
@@ -4574,6 +4659,20 @@ class String
   #     # => "\u0000\t\n\v\f\r abc\u0000\t\n\v\f\r "
   #     s.strip # => "abc"
   #
+  # If `selectors` are given, removes characters of `selectors` from both ends of
+  # `self`:
+  #
+  #     s = "---abc+++"
+  #     s.strip("-+") # => "abc"
+  #     s.strip("+-") # => "abc"
+  #
+  # `selectors` must be valid character selectors (see [Character
+  # Selectors](rdoc-ref:character_selectors.rdoc)), and may use any of its valid
+  # forms, including negation, ranges, and escapes:
+  #
+  #     "01234abc56789".strip("0-9") # "abc"
+  #     "01234abc56789".strip("0-9", "^4-6") # "4abc56"
+  #
   # Related: see [Converting to New
   # String](rdoc-ref:String@Converting+to+New+String).
   #
@@ -4581,7 +4680,7 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - strip! -> self or nil
+  #   - strip!(*selectors) -> self or nil
   # -->
   # Like String#strip, except that:
   #
@@ -4742,7 +4841,7 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - swapcase(mapping) -> new_string
+  #   - swapcase(mapping = :ascii) -> new_string
   # -->
   # Returns a string containing the characters in `self`, with cases reversed:
   #
@@ -4751,16 +4850,28 @@ class String
   #
   # Examples:
   #
-  #     'Hello World!'.swapcase # => "hELLO wORLD!"
-  #     'тест'.swapcase         # => "ТЕСТ"
+  #     'Hello'.swapcase        # => "hELLO"
+  #     'Straße'.swapcase       # => "sTRASSE"
+  #     'Привет'.swapcase       # => "пРИВЕТ"
+  #     'RubyGems.org'.swapcase # => "rUBYgEMS.ORG"
+  #
+  # The sizes of `self` and the upcased result may differ:
   #
-  # Some characters (and even character sets) do not have casing:
+  #     s = 'Straße'
+  #     s.size          # => 6
+  #     s.swapcase      # => "sTRASSE"
+  #     s.swapcase.size # => 7
   #
-  #     '12345'.swapcase    # => "12345"
-  #     'こんにちは'.swapcase # => "こんにちは"
+  # Some characters (and some character sets) do not have upcase and downcase
+  # versions; see [Case Mapping](rdoc-ref:case_mapping.rdoc):
   #
-  # The casing may be affected by the given `mapping`; see [Case
-  # Mapping](rdoc-ref:case_mapping.rdoc).
+  #     s = '1, 2, 3, ...'
+  #     s.swapcase == s # => true
+  #     s = 'こんにちは'
+  #     s.swapcase == s # => true
+  #
+  # The casing is affected by the given `mapping`, which may be `:ascii`, `:fold`,
+  # or `:turkic`; see [Case Mappings](rdoc-ref:case_mapping.rdoc@Case+Mappings).
   #
   # Related: see [Converting to New
   # String](rdoc-ref:String@Converting+to+New+String).
@@ -5149,16 +5260,13 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - undump -> string
+  #   - undump -> new_string
   # -->
-  # Returns an unescaped version of `self`:
-  #
-  #     s_orig = "\f\x00\xff\\\""    # => "\f\u0000\xFF\\\""
-  #     s_dumped = s_orig.dump       # => "\"\\f\\x00\\xFF\\\\\\\"\""
-  #     s_undumped = s_dumped.undump # => "\f\u0000\xFF\\\""
-  #     s_undumped == s_orig         # => true
+  # Inverse of String#dump; returns a copy of `self` with changes of the kinds
+  # made by String#dump "undone."
   #
-  # Related: String#dump (inverse of String#undump).
+  # Related: see [Converting to New
+  # String](rdoc-ref:String@Converting+to+New+String).
   #
   def undump: () -> String
 
@@ -5179,21 +5287,22 @@ class String
   #
   # The encoding of `self` must be one of:
   #
-  # *   Encoding::UTF_8
-  # *   Encoding::UTF_16BE
-  # *   Encoding::UTF_16LE
-  # *   Encoding::UTF_32BE
-  # *   Encoding::UTF_32LE
-  # *   Encoding::GB18030
-  # *   Encoding::UCS_2BE
-  # *   Encoding::UCS_4BE
+  # *   `Encoding::UTF_8`.
+  # *   `Encoding::UTF_16BE`.
+  # *   `Encoding::UTF_16LE`.
+  # *   `Encoding::UTF_32BE`.
+  # *   `Encoding::UTF_32LE`.
+  # *   `Encoding::GB18030`.
+  # *   `Encoding::UCS_2BE`.
+  # *   `Encoding::UCS_4BE`.
   #
   # Examples:
   #
-  #     "a\u0300".unicode_normalize      # => "a"
-  #     "\u00E0".unicode_normalize(:nfd) # => "a "
+  #     "a\u0300".unicode_normalize       # => "à"  # Lowercase 'a' with grave accens.
+  #     "a\u0300".unicode_normalize(:nfd) # => "à"  # Same.
   #
-  # Related: String#unicode_normalize!, String#unicode_normalized?.
+  # Related: see [Converting to New
+  # String](rdoc-ref:String@Converting+to+New+String).
   #
   def unicode_normalize: (?:nfc | :nfd | :nfkc | :nfkd form) -> self
 
@@ -5239,7 +5348,7 @@ class String
   #   - unpack(template, offset: 0) -> array
   # -->
   # Extracts data from `self` to form new objects; see [Packed
-  # Data](rdoc-ref:packed_data.rdoc).
+  # Data](rdoc-ref:language/packed_data.rdoc).
   #
   # With a block given, calls the block with each unpacked object.
   #
@@ -5256,7 +5365,7 @@ class String
   #   - unpack1(template, offset: 0) -> object
   # -->
   # Like String#unpack with no block, but unpacks and returns only the first
-  # extracted object. See [Packed Data](rdoc-ref:packed_data.rdoc).
+  # extracted object. See [Packed Data](rdoc-ref:language/packed_data.rdoc).
   #
   # Related: see [Converting to
   # Non-String](rdoc-ref:String@Converting+to+Non--5CString).
@@ -5265,17 +5374,35 @@ class String
 
   # <!--
   #   rdoc-file=string.c
-  #   - upcase(mapping) -> string
+  #   - upcase(mapping = :ascii) -> new_string
   # -->
-  # Returns a string containing the upcased characters in `self`:
+  # Returns a new string containing the upcased characters in `self`:
   #
-  #     s = 'Hello World!' # => "Hello World!"
-  #     s.upcase           # => "HELLO WORLD!"
+  #     'hello'.upcase        # => "HELLO"
+  #     'straße'.upcase       # => "STRASSE"
+  #     'привет'.upcase       # => "ПРИВЕТ"
+  #     'RubyGems.org'.upcase # => "RUBYGEMS.ORG"
+  #
+  # The sizes of `self` and the upcased result may differ:
+  #
+  #     s = 'Straße'
+  #     s.size        # => 6
+  #     s.upcase      # => "STRASSE"
+  #     s.upcase.size # => 7
+  #
+  # Some characters (and some character sets) do not have upcase and downcase
+  # versions; see [Case Mapping](rdoc-ref:case_mapping.rdoc):
+  #
+  #     s = '1, 2, 3, ...'
+  #     s.upcase == s # => true
+  #     s = 'こんにちは'
+  #     s.upcase == s # => true
   #
-  # The casing may be affected by the given `mapping`; see [Case
-  # Mapping](rdoc-ref:case_mapping.rdoc).
+  # The casing is affected by the given `mapping`, which may be `:ascii`, `:fold`,
+  # or `:turkic`; see [Case Mappings](rdoc-ref:case_mapping.rdoc@Case+Mappings).
   #
-  # Related: String#upcase!, String#downcase, String#downcase!.
+  # Related: see [Converting to New
+  # String](rdoc-ref:String@Converting+to+New+String).
   #
   def upcase: () -> String
             | (:ascii | :lithuanian | :turkic) -> String
@@ -5286,18 +5413,12 @@ class String
   #   rdoc-file=string.c
   #   - upcase!(mapping) -> self or nil
   # -->
-  # Upcases the characters in `self`; returns `self` if any changes were made,
-  # `nil` otherwise:
-  #
-  #     s = 'Hello World!' # => "Hello World!"
-  #     s.upcase!          # => "HELLO WORLD!"
-  #     s                  # => "HELLO WORLD!"
-  #     s.upcase!          # => nil
+  # Like String#upcase, except that:
   #
-  # The casing may be affected by the given `mapping`; see [Case
-  # Mapping](rdoc-ref:case_mapping.rdoc).
+  # *   Changes character casings in `self` (not in a copy of `self`).
+  # *   Returns `self` if any changes are made, `nil` otherwise.
   #
-  # Related: String#upcase, String#downcase, String#downcase!.
+  # Related: See [Modifying](rdoc-ref:String@Modifying).
   #
   def upcase!: () -> self?
              | (:ascii | :lithuanian | :turkic) -> self?
@@ -5314,20 +5435,28 @@ class String
   # `self.succ`, and so on; the sequence terminates when value `other_string` is
   # reached; returns `self`:
   #
-  #     'a8'.upto('b6') {|s| print s, ' ' } # => "a8"
+  #     a = []
+  #     'a'.upto('f') {|c| a.push(c) }
+  #     a # => ["a", "b", "c", "d", "e", "f"]
   #
-  # Output:
+  #     a = []
+  #     'Ж'.upto('П') {|c| a.push(c) }
+  #     a # => ["Ж", "З", "И", "Й", "К", "Л", "М", "Н", "О", "П"]
   #
-  #     a8 a9 b0 b1 b2 b3 b4 b5 b6
+  #     a = []
+  #     'よ'.upto('ろ') {|c| a.push(c) }
+  #     a # => ["よ", "ら", "り", "る", "れ", "ろ"]
+  #
+  #     a = []
+  #     'a8'.upto('b6') {|c| a.push(c) }
+  #     a # => ["a8", "a9", "b0", "b1", "b2", "b3", "b4", "b5", "b6"]
   #
   # If argument `exclusive` is given as a truthy object, the last value is
   # omitted:
   #
-  #     'a8'.upto('b6', true) {|s| print s, ' ' } # => "a8"
-  #
-  # Output:
-  #
-  #     a8 a9 b0 b1 b2 b3 b4 b5
+  #     a = []
+  #     'a'.upto('f', true) {|c| a.push(c) }
+  #     a # => ["a", "b", "c", "d", "e"]
   #
   # If `other_string` would not be reached, does not call the block:
   #
@@ -5338,6 +5467,8 @@ class String
   #
   #     'a8'.upto('b6') # => #<Enumerator: "a8":upto("b6")>
   #
+  # Related: see [Iterating](rdoc-ref:String@Iterating).
+  #
   def upto: (string other_string, ?boolish exclusive) -> Enumerator[String, self]
           | (string other_string, ?boolish exclusive) { (String s) -> void } -> self
 
@@ -5345,11 +5476,14 @@ class String
   #   rdoc-file=string.c
   #   - valid_encoding? -> true or false
   # -->
-  # Returns `true` if `self` is encoded correctly, `false` otherwise:
+  # Returns whether `self` is encoded correctly:
   #
-  #     "\xc2\xa1".force_encoding(Encoding::UTF_8).valid_encoding? # => true
-  #     "\xc2".force_encoding(Encoding::UTF_8).valid_encoding?     # => false
-  #     "\x80".force_encoding(Encoding::UTF_8).valid_encoding?     # => false
+  #     s = 'Straße'
+  #     s.valid_encoding?                                 # => true
+  #     s.encoding                                        # => #<Encoding:UTF-8>
+  #     s.force_encoding(Encoding::ASCII).valid_encoding? # => false
+  #
+  # Related: see [Querying](rdoc-ref:String@Querying).
   #
   def valid_encoding?: () -> bool
 end