summaryrefslogtreecommitdiff
diff options
authorBurdetteLamar <[email protected]>2025-07-12 11:49:41 -0500
committerPeter Zhu <[email protected]>2025-07-12 13:08:14 -0400
commite1bc92d00b744fb453f494aefbf34ed12a0f9087 (patch)
tree45f7350d7ee6ce869ec5298adeb0ddf71e25357d
parentb0db93c002d07a60105d32299530e2a0ee88ee5f (diff)
[DOC] Tweaks for String#deleteHEADmaster
-rw-r--r--doc/string/delete.rdoc79
-rw-r--r--string.c8
2 files changed, 80 insertions, 7 deletions
diff --git a/doc/string/delete.rdoc b/doc/string/delete.rdoc
new file mode 100644
index 0000000000..e8ff4c0ae4
--- /dev/null
+++ b/doc/string/delete.rdoc
@@ -0,0 +1,79 @@
+Returns a new string that is a copy of +self+ with certain characters removed;
+the removed characters are all instances of those specified by the given string +selectors+.
+
+For one 1-character selector,
+removes all instances of that character:
+
+ s = 'abracadabra'
+ s.delete('a') # => "brcdbr"
+ s.delete('b') # => "aracadara"
+ s.delete('x') # => "abracadabra"
+ s.delete('') # => "abracadabra"
+
+ s = 'тест'
+ s.delete('т') # => "ес"
+ s.delete('е') # => "тст"
+
+ s = 'よろしくお願いします'
+ s.delete('よ') # => "ろしくお願いします"
+ s.delete('し') # => "よろくお願います"
+
+For one multi-character selector,
+removes all instances of the specified characters:
+
+ s = 'abracadabra'
+ s.delete('ab') # => "rcdr"
+ s.delete('abc') # => "rdr"
+ s.delete('abcd') # => "rr"
+ s.delete('abcdr') # => ""
+ s.delete('abcdrx') # => ""
+
+Order and repetition do not matter:
+
+ s.delete('ba') == s.delete('ab') # => true
+ s.delete('baab') == s.delete('ab') # => true
+
+For multiple selectors,
+forms a single selector that is the intersection of characters in all selectors
+and removes all instances of characters specified by that selector:
+
+ s = 'abcdefg'
+ s.delete('abcde', 'dcbfg') == s.delete('bcd') # => true
+ s.delete('abc', 'def') == s.delete('') # => 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.delete('^bc') # => "bcb" # Deletes all except 'b' and 'c'.
+
+- A hyphen (<tt>'-'</tt>) between two other characters defines a _range_ of characters:
+
+ s = 'abracadabra'
+ s.delete('a-c') # => "rdr" # Deletes all 'a', 'b', and 'c'.
+
+- A backslash (<tt>'\'</tt>) acts as an escape for a caret, a hyphen,
+ or another backslash:
+
+ s = 'abracadabra'
+ s.delete('\^bc') # => "araadara" # Deletes all '^', 'b', and 'c'.
+ s.delete('a\-c') # => "brdbr" # Deletes all 'a', '-', and 'c'.
+ 'foo\bar\baz'.delete('\\') # => "foobarbaz" # Deletes all '\'.
+
+These usages may be mixed:
+
+ s = 'abracadabra'
+ s.delete('a-cq-t') # => "d" # Multiple ranges.
+ s.delete('ac-d') # => "brbr" # Range mixed with plain characters.
+ s.delete('^a-c') # => "abacaaba" # Range mixed with negation.
+
+For multiple selectors, all forms may be used, including negations, ranges, and escapes.
+
+ s = 'abracadabra'
+ s.delete('^abc', '^def') == s.delete('^abcdef') # => true
+ s.delete('a-e', 'c-g') == s.delete('cde') # => true
+ s.delete('^abc', 'c-g') == s.delete('defg') # => true
+
+Related: see {Converting to New String}[rdoc-ref:String@Converting+to+New+String].
diff --git a/string.c b/string.c
index b1dccce4ef..34af14de1f 100644
--- a/string.c
+++ b/string.c
@@ -8937,13 +8937,7 @@ rb_str_delete_bang(int argc, VALUE *argv, VALUE str)
* call-seq:
* delete(*selectors) -> new_string
*
- * 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"
+ * :include: doc/string/delete.rdoc
*
*/
close