https://git.ruby-lang.org/ruby.git/commit/?id=6e44de752e

From 6e44de752ea4e82d07feaf4816e838017b9d0788 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Y...>
Date: Fri, 22 Jan 2021 15:01:09 -0600
Subject: What's Here for String RDoc (#4093)

* What's Here for String RDoc

diff --git a/string.c b/string.c
index 8c5bc3e..4957cc3 100644
--- a/string.c
+++ b/string.c
@@ -11525,6 +11525,254 @@ rb_enc_interned_str_cstr(const char *ptr, rb_encoding *enc) https://github.com/ruby/ruby/blob/trunk/string.c#L11525
  *  without a ``!'' return a new String.  However, there are
  *  exceptions, such as String#[]=.
  *
+ *  == What's Here
+ *
+ *  First, what's elsewhere. \String includes the module Comparable,
+ *  which provides several very useful methods.
+ *
+ *  Here, class \String provides methods that are useful for:
+ *
+ *  - {Creating a String}[#class-String-label-Methods+for+Creating+a+String]
+ *  - {Frozen/Unfrozen Strings}[#class-String-label-Methods+for+a+Frozen-2FUnfrozen+String]
+ *  - {Querying}[#class-String-label-Methods+for+Querying]
+ *  - {Comparing}[#class-String-label-Methods+for+Comparing]
+ *  - {Modifying a String}[#class-String-label-Methods+for+Modifying+a+String]
+ *  - {Converting to New String}[#class-String-label-Methods+for+Converting+to+New+String]
+ *  - {Converting to Non-String}[#class-String-label-Methods+for+Converting+to+Non--5CString]
+ *  - {Iterating}[#class-String-label-Methods+for+Iterating]
+ *
+ *  === 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
+ *
+ *  - {#+string}[#method-i-2B-40]:: Returns a string that is not frozen:
+ *                                  +self+, if not frozen; +self.dup+ otherwise.
+ *  - {#-string}[#method-i-2D-40]:: 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).
+ *  - #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_
+ *
+ *  - {#=~}[#method-i-3D~]:: Returns the index of the first substring that matches a given Regexp or other object;
+ *                           returns +nil+ if no match is found.
+ *  - #index:: Returns the index of the _first_ occurrence of a given substring;
+ *             returns +nil+ if none found.
+ *  - #rindex:: Returns the index of the _last_ occurrence of a given substring;
+ *              returns +nil+ if none found.
+ *  - #include?:: Returns +true+ if the string contains a given substring; +false+ otherwise.
+ *  - #match:: Returns a MatchData object if the string matches a given Regexp; +nil+ otherwise.
+ *  - #match?:: Returns +true+ if the string matches a given Regexp; +false+ otherwise.
+ *  - #start_with?:: Returns +true+ if the string begins with any of the given substrings.
+ *  - #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 string.
+ *  - #unicode_normalized?:: Returns +true+ if the string is in Unicode normalized form; +false+ otherwise.
+ *  - #valid_encoding?:: Returns +true+ if the string contains only characters that are valid
+ *                       for its encoding.
+ *  - #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
+ *
+ *  - {#==, #===}[#method-i-3D-3D]:: 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.
+ *  - {#<=>}[#method-i-3C-3D-3E]:: Returns -1, 0, or 1 as a given other string is smaller than, equal to, or larger than +self+.
+ *  - #casecmp:: Ignoring case, returns -1, 0, or 1 as a given
+ *               other string is smaller than, equal to, or larger than +self+.
+ *  - #casecmp?:: Returns +true+ if the string is equal to a given string after Unicode case folding;
+ *                +false+ otherwise.
+ *
+ *  === Methods for Modifying +self+
+ *
+ *  Each of these methods modifies +self+.
+ *
+ *  _Insertion_
+ *
+ *  - #insert:: Returns +self+ with a given string inserted at a given offset.
+ *  - #<<:: Returns +self+ concatenated with a given string or integer.
+ *
+ *  _Substitution_
+ *
+ *  - #sub!:: Replaces the first substring that matches a given pattern with a 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.
+ *  - #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.
+ *  - #tr!:: Replaces specified characters in +self+ with specified replacement characters;
+ *           returns +self+ if any changes, +nil+ otherwise.
+ *  - #tr_s!:: Replaces specified characters in +self+ with specified replacement 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;
+ *                   returns +self+ if any changes, +nil+ otherwise.
+ *  - #downcase!:: Downcases all characters; returns +self+ if any changes, +nil+ otherwise.
+ *  - #upcase!:: Upcases all characters; returns +self+ if any changes, +nil+ otherwise.
+ *  - #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.
+ *  - #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+.
+ *  - #slice!, #[]=:: Removes a substring determined by a given index, start/length, range, regexp, or substring.
+ *  - #squeeze!:: Removes contiguous duplicate characters; returns +self+.
+ *  - #delete!:: Removes characters as determined by the intersection of substring arguments.
+ *  - #lstrip!:: Removes leading whitespace; returns +self+ if any changes, +nil+ otherwise.
+ *  - #rstrip!:: Removes trailing whitespace; returns +self+ if any changes, +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.
+ *  - #chop!:: Removes trailing whitespace if found, otherwise removes the last character;
+ *             returns +self+ if any changes, +nil+ otherwise.
+ *
+ *  === Methods for Converting to New \String
+ *
+ *  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 +self+ and a given other string.
+ *  - #center:: Returns a copy of +self+ centered between pad substring.
+ *  - #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 given other string.
+ *  - #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.
+ *  - #scrub:: Returns a copy of +self+ with each invalid byte replaced with a given character.
+ *  - #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.
+ *
+ *  _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 <tt>\xNN</tt> notation replace by <tt>\uNNNN</tt> notation
+ *              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;.
+ *  - #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+.
+ *  - #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.
+ *  - #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 (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/