Merge pull request #242 from gfldex/master

add Str::trans

Author: gfldex

doc/Type/Str.pod

@@ -681,6 +681,28 @@ Example:
 
     "aå«".ords # (97 229 171)
 
+=head2 method trans
+
+Replaces one or many substrings with one or many strings. Ranges are supported, both for keys and values. Regexes work as keys. When called with C<:complemet> anything but the matched value or range is replaced with a single value. With C<:delete> the matched characters are removed. Combining C<:complement> and C<:delete> will remove anything but the mached values. The adverb C<:squash> will reduce repeated matched characters to a single character. 
+
+Example:
+
+    my $str = 'say $x<b> && $y<a>';
+    $str.=trans( '<' => '&lt;' );
+    $str.=trans( '<' => '&lt;', '>' => '&gt;' );
+    
+    $str.=trans( [ '<'   , '>'   , '&' ] =>
+                 [ '&lt;', '&gt;', '&amp;' ]);
+    
+    $str.=trans( ['a'..'y'] => ['A'..'z'] );
+
+    "abcdefghij".trans(/<[aeiou]> \w/ => ''); # «cdgh»
+
+    "a123b123c".trans(['a'..'z'] => 'x', :complement); # «axxxbxxxc»
+    "a123b123c".trans('23' => '', :delete); # «a1b1c»
+    "aaa1123bb123c".trans('a'..'z' => 'A'..'Z', :squash); # «A1123B123C»
+    "aaa1123bb123c".trans('a'..'z' => 'x', :complement, :squash); # «aaaxbbxc»
+
 =head2 method indent
 
     proto method indent($)