doc/character_selectors.rdoc

   1 = Character Selectors
   2
   3 == Character Selector
   4
   5 A _character_ _selector_ is a string argument accepted by certain Ruby methods.
   6 Each of these instance methods accepts one or more character selectors:
   7
   8 - String#tr(selector, replacements): returns a new string.
   9 - String#tr!(selector, replacements): returns +self+ or +nil+.
  10 - String#tr_s(selector, replacements): returns a new string.
  11 - String#tr_s!(selector, replacements): returns +self+ or +nil+.
  12 - String#count(*selectors): returns the count of the specified characters.
  13 - String#delete(*selectors): returns a new string.
  14 - String#delete!(*selectors): returns +self+ or +nil+.
  15 - String#squeeze(*selectors): returns a new string.
  16 - String#squeeze!(*selectors): returns +self+ or +nil+.
  17
  18 A character selector identifies zero or more characters in +self+
  19 that are to be operands for the method.
  20
  21 In this section, we illustrate using method String#delete(selector),
  22 which deletes the selected characters.
  23
  24 In the simplest case, the characters selected are exactly those
  25 contained in the selector itself:
  26
  27   'abracadabra'.delete('a')   # => "brcdbr"
  28   'abracadabra'.delete('ab')  # => "rcdr"
  29   'abracadabra'.delete('abc') # => "rdr"
  30   '0123456789'.delete('258')  # => "0134679"
  31   '!@#$%&*()_+'.delete('+&#') # => "!@$%*()_"
  32   'тест'.delete('т')          # => "ес"
  33   'こんにちは'.delete('に')     # => "こんちは"
  34
  35 Note that order and repetitions do not matter:
  36
  37   'abracadabra'.delete('dcab') # => "rr"
  38   'abracadabra'.delete('aaaa') # => "brcdbr"
  39
  40 In a character selector, these three characters get special treatment:
  41
  42 - A leading caret (<tt>'^'</tt>) functions as a "not" operator
  43   for the characters to its right:
  44
  45     'abracadabra'.delete('^bc') # => "bcb"
  46     '0123456789'.delete('^852') # => "258"
  47
  48 - A hyphen (<tt>'-'</tt>) between two other characters
  49   defines a range of characters instead of a plain string of characters:
  50
  51     'abracadabra'.delete('a-d') # => "rr"
  52     '0123456789'.delete('4-7')  # => "012389"
  53     '!@#$%&*()_+'.delete(' -/') # => "@^_"
  54
  55     # May contain more than one range.
  56     'abracadabra'.delete('a-cq-t') # => "d"
  57
  58     # Ranges may be mixed with plain characters.
  59     '0123456789'.delete('67-950-23') # => "4"
  60
  61     # Ranges may be mixed with negations.
  62     'abracadabra'.delete('^a-c') # => "abacaaba"
  63
  64 - A backslash (<tt>'\'</tt>) acts as an escape for a caret, a hyphen,
  65   or another backslash:
  66
  67     'abracadabra^'.delete('\^bc')   # => "araadara"
  68     'abracadabra-'.delete('a\-d')   # => "brcbr"
  69     "hello\r\nworld".delete("\r")   # => "hello\nworld"
  70     "hello\r\nworld".delete("\\r")  # => "hello\r\nwold"
  71     "hello\r\nworld".delete("\\\r") # => "hello\nworld"
  72
  73 == Multiple Character Selectors
  74
  75 These instance methods accept multiple character selectors:
  76
  77 - String#count(*selectors): returns the count of the specified characters.
  78 - String#delete(*selectors): returns a new string.
  79 - String#delete!(*selectors): returns +self+ or +nil+.
  80 - String#squeeze(*selectors): returns a new string.
  81 - String#squeeze!(*selectors): returns +self+ or +nil+.
  82
  83 In effect, the given selectors are formed into a single selector
  84 consisting of only those characters common to _all_ of the given selectors.
  85
  86 All forms of selectors may be used, including negations, ranges, and escapes.
  87
  88 Each of these pairs of method calls is equivalent:
  89
  90   s.delete('abcde', 'dcbfg')
  91   s.delete('bcd')
  92
  93   s.delete('^abc', '^def')
  94   s.delete('^abcdef')
  95
  96   s.delete('a-e', 'c-g')
  97   s.delete('cde')