[DOC] Enhanced RDoc for String (#5635)

Treats:

    #count
    #delete
    #delete!
    #squeeze
    #squeeze!

Adds section "Multiple Character Selectors" to doc/character_selectors.rdoc.

Co-authored-by: Peter Zhu <peter@peterzhu.ca>

doc/character_selectors.rdoc

@@ -1,15 +1,19 @@
 == Character Selectors
 
+=== Character Selector
+
 A _character_ _selector_ is a string argument accepted by certain Ruby methods.
 Each of these instance methods accepts one or more character selectors:
 
 - String#tr(selector, replacements): returns a new string.
-- String#tr!(selector, replacements): returns +self+.
+- String#tr!(selector, replacements): returns +self+ or +nil+.
 - String#tr_s(selector, replacements): returns a new string.
-- String#tr_s!(selector, replacements): returns +self+.
+- String#tr_s!(selector, replacements): returns +self+ or +nil+.
+- String#count(*selectors): returns the count of the specified characters.
 - String#delete(*selectors): returns a new string.
-- String#delete!(*selectors): returns +self+.
+- String#delete!(*selectors): returns +self+ or +nil+.
-- String#count(*selectors): counts specified characters.
+- String#squeeze(*selectors): returns a new string.
+- String#squeeze!(*selectors): returns +self+ or +nil+.
 
 A character selector identifies zero or more characters in +self+
 that are to be operands for the method.
@@ -65,3 +69,29 @@ In a character selector, these three characters get special treatment:
     "hello\r\nworld".delete("\r")   # => "hello\nworld"
     "hello\r\nworld".delete("\\r")  # => "hello\r\nwold"
     "hello\r\nworld".delete("\\\r") # => "hello\nworld"
+
+=== Multiple Character Selectors
+
+These instance methods accept multiple character selectors:
+
+- String#count(*selectors): returns the count of the specified characters.
+- String#delete(*selectors): returns a new string.
+- String#delete!(*selectors): returns +self+ or +nil+.
+- String#squeeze(*selectors): returns a new string.
+- String#squeeze!(*selectors): returns +self+ or +nil+.
+
+In effect, the given selectors are formed into a single selector
+consisting of only those characters common to _all_ of the given selectors.
+
+All forms of selectors may be used, including negations, ranges, and escapes.
+
+Each of these pairs of method calls is equivalent:
+
+  s.delete('abcde', 'dcbfg')
+  s.delete('bcd')
+
+  s.delete('^abc', '^def')
+  s.delete('^abcdef')
+
+  s.delete('a-e', 'c-g')
+  s.delete('cde')

string.c

@@ -8158,10 +8158,11 @@ tr_find(unsigned int c, const char table[TR_TABLE_SIZE], VALUE del, VALUE nodel)
 
 /*
  *  call-seq:
- *     str.delete!([other_str]+)   -> str or nil
+ *    delete!(*selectors) -> self or nil
+ *
+ *  Like String#delete, but modifies +self+ in place.
+ *  Returns +self+ if any changes were made, +nil+ otherwise.
  *
- *  Performs a <code>delete</code> operation in place, returning <i>str</i>, or
- *  <code>nil</code> if <i>str</i> was not modified.
  */
 
 static VALUE
@@ -8228,16 +8229,16 @@ rb_str_delete_bang(int argc, VALUE *argv, VALUE str)
 
 /*
  *  call-seq:
- *     str.delete([other_str]+)   -> new_str
+ *    delete(*selectors) -> new_string
  *
- *  Returns a copy of <i>str</i> with all characters in the intersection of its
+ *  Returns a copy of +self+ with characters specified by +selectors+ removed
- *  arguments deleted. Uses the same rules for building the set of characters as
+ *  (see {Multiple Character Selectors}[rdoc-ref:character_selectors.rdoc@Multiple+Character+Selectors]):
- *  String#count.
  *
  *     "hello".delete "l","lo"        #=> "heo"
  *     "hello".delete "lo"            #=> "he"
  *     "hello".delete "aeiou", "^e"   #=> "hell"
  *     "hello".delete "ej-m"          #=> "ho"
+ *
  */
 
 static VALUE
@@ -8251,10 +8252,10 @@ rb_str_delete(int argc, VALUE *argv, VALUE str)
 
 /*
  *  call-seq:
- *     str.squeeze!([other_str]*)   -> str or nil
+ *    squeeze!(*selectors) -> self or nil
  *
- *  Squeezes <i>str</i> in place, returning either <i>str</i>, or
+ *  Like String#squeeze, but modifies +self+ in place.
- *  <code>nil</code> if no changes were made.
+ *  Returns +self+ if any changes were made, +nil+ otherwise.
  */
 
 static VALUE
@@ -8335,17 +8336,19 @@ rb_str_squeeze_bang(int argc, VALUE *argv, VALUE str)
 
 /*
  *  call-seq:
- *     str.squeeze([other_str]*)    -> new_str
+ *     str.squeeze(*selectors) -> new_string
  *
- *  Builds a set of characters from the <i>other_str</i> parameter(s)
+ *  Returns a copy of +self+ with characters specified by +selectors+ "squeezed"
- *  using the procedure described for String#count. Returns a new
+ *  (see {Multiple Character Selectors}[rdoc-ref:character_selectors.rdoc@Multiple+Character+Selectors]):
- *  string where runs of the same character that occur in this set are
+ *
- *  replaced by a single character. If no arguments are given, all
+ *  "Squeezed" means that each multiple-character run of a selected character
- *  runs of identical characters are replaced by a single character.
+ *  is squeezed down to a single character;
+ *  with no arguments given, squeezes all characters:
  *
  *     "yellow moon".squeeze                  #=> "yelow mon"
  *     "  now   is  the".squeeze(" ")         #=> " now is the"
  *     "putters shoot balls".squeeze("m-z")   #=> "puters shot balls"
+ *
  */
 
 static VALUE
@@ -8400,15 +8403,11 @@ rb_str_tr_s(VALUE str, VALUE src, VALUE repl)
 
 /*
  *  call-seq:
- *     str.count([other_str]+)   -> integer
+ *    count(*selectors) -> integer
  *
- *  Each +other_str+ parameter defines a set of characters to count.  The
+ *  Returns the total number of characters in +self+
- *  intersection of these sets defines the characters to count in +str+.  Any
+ *  that are specified by the given +selectors+
- *  +other_str+ that starts with a caret <code>^</code> is negated.  The
+ *  (see {Multiple Character Selectors}[rdoc-ref:character_selectors.rdoc@Multiple+Character+Selectors]):
- *  sequence <code>c1-c2</code> means all characters between c1 and c2.  The
- *  backslash character <code>\\</code> can be used to escape <code>^</code> or
- *  <code>-</code> and is otherwise ignored unless it appears at the end of a
- *  sequence or the end of a +other_str+.
  *
  *     a = "hello world"
  *     a.count "lo"                   #=> 5