diff --git a/doc/character_selectors.rdoc b/doc/character_selectors.rdoc
index dc55491a26..e01b0e6a25 100644
--- a/doc/character_selectors.rdoc
+++ b/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#count(*selectors): counts specified characters.
+- String#delete!(*selectors): returns +self+ or +nil+.
+- 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')
diff --git a/string.c b/string.c
index 3bc250122b..7ac11c31d4 100644
--- a/string.c
+++ b/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 delete
operation in place, returning str, or
- * nil
if str 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 str with all characters in the intersection of its
- * arguments deleted. Uses the same rules for building the set of characters as
- * String#count.
+ * Returns a copy of +self+ with characters specified by +selectors+ removed
+ * (see {Multiple Character Selectors}[rdoc-ref:character_selectors.rdoc@Multiple+Character+Selectors]):
*
* "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 str in place, returning either str, or
- * nil
if no changes were made.
+ * Like String#squeeze, but modifies +self+ in place.
+ * 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 other_str parameter(s)
- * using the procedure described for String#count. Returns a new
- * string where runs of the same character that occur in this set are
- * replaced by a single character. If no arguments are given, all
- * runs of identical characters are replaced by a single character.
+ * Returns a copy of +self+ with characters specified by +selectors+ "squeezed"
+ * (see {Multiple Character Selectors}[rdoc-ref:character_selectors.rdoc@Multiple+Character+Selectors]):
+ *
+ * "Squeezed" means that each multiple-character run of a selected 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
- * intersection of these sets defines the characters to count in +str+. Any
- * +other_str+ that starts with a caret ^
is negated. The
- * sequence c1-c2
means all characters between c1 and c2. The
- * backslash character \\
can be used to escape ^
or
- * -
and is otherwise ignored unless it appears at the end of a
- * sequence or the end of a +other_str+.
+ * Returns the total number of characters in +self+
+ * 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