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