[DOC] Tweaks for String#count

doc/string/count.rdoc

@@ -0,0 +1,78 @@
+Returns the total number of characters in +self+ that are specified by the given selectors.
+
+For one 1-character selector,
+returns the count of instances of that character:
+
+  s = 'abracadabra'
+  s.count('a') # => 5
+  s.count('b') # => 2
+  s.count('x') # => 0
+  s.count('')  # => 0
+
+  s = 'тест'
+  s.count('т')  # => 2
+  s.count('е')  # => 1
+
+  s = 'よろしくお願いします'
+  s.count('よ')  # => 1
+  s.count('し')  # => 2
+
+For one multi-character selector,
+returns the count of instances for all specified characters:
+
+  s = 'abracadabra'
+  s.count('ab')     # => 7
+  s.count('abc')    # => 8
+  s.count('abcd')   # => 9
+  s.count('abcdr')  # => 11
+  s.count('abcdrx') # => 11
+
+Order and repetition do not matter:
+
+  s.count('ba')   == s.count('ab') # => true
+  s.count('baab') == s.count('ab') # => true
+
+For multiple selectors,
+forms a single selector that is the intersection of characters in all selectors
+and returns the count of instances for that selector:
+
+  s = 'abcdefg'
+  s.count('abcde', 'dcbfg') == s.count('bcd') # => true
+  s.count('abc', 'def')     == s.count('')    # => true
+
+In a character selector, three characters get special treatment:
+
+- A caret (<tt>'^'</tt>) functions as a _negation_ operator
+  for the immediately following characters:
+
+    s = 'abracadabra'
+    s.count('^bc') # => 8  # Count of all except 'b' and 'c'.
+
+- A hyphen (<tt>'-'</tt>) between two other characters defines a _range_ of characters:
+
+    s = 'abracadabra'
+    s.count('a-c') # => 8  # Count of all 'a', 'b', and 'c'.
+
+- A backslash (<tt>'\'</tt>) acts as an escape for a caret, a hyphen,
+  or another backslash:
+
+    s = 'abracadabra'
+    s.count('\^bc')           # => 3  # Count of '^', 'b', and 'c'.
+    s.count('a\-c')           # => 6  # Count of 'a', '-', and 'c'.
+    'foo\bar\baz'.count('\\') # => 2  # Count of '\'.
+
+These usages may be mixed:
+
+  s = 'abracadabra'
+  s.count('a-cq-t') # => 10  # Multiple ranges.
+  s.count('ac-d')   # => 7   # Range mixed with plain characters.
+  s.count('^a-c')   # => 3   # Range mixed with negation.
+
+For multiple selectors, all forms may be used, including negations, ranges, and escapes.
+
+  s = 'abracadabra'
+  s.count('^abc', '^def') == s.count('^abcdef') # => true
+  s.count('a-e', 'c-g')   == s.count('cde')     # => true
+  s.count('^abc', 'c-g')  == s.count('defg')    # => true
+
+Related: see {Querying}[rdoc-ref:String@Querying].

string.c

@@ -9111,23 +9111,7 @@ rb_str_tr_s(VALUE str, VALUE src, VALUE repl)
  *  call-seq:
  *    count(*selectors) -> integer
  *
- *  Returns the total number of characters in +self+
+ *  :include: doc/string/count.rdoc
- *  that are specified by the given +selectors+
- *  (see {Multiple Character Selectors}[rdoc-ref:character_selectors.rdoc@Multiple+Character+Selectors]):
- *
- *     a = "hello world"
- *     a.count "lo"                   #=> 5
- *     a.count "lo", "o"              #=> 2
- *     a.count "hello", "^l"          #=> 4
- *     a.count "ej-m"                 #=> 4
- *
- *     "hello^world".count "\\^aeiou" #=> 4
- *     "hello-world".count "a\\-eo"   #=> 4
- *
- *     c = "hello world\\r\\n"
- *     c.count "\\"                   #=> 2
- *     c.count "\\A"                  #=> 0
- *     c.count "X-\\w"                #=> 3
  */
 
 static VALUE