txt: ## trans.md
  trans
  
  Combined from primary sources listed below.
  
  # [In Str](#___top "go to top of document")[§](#(Str)_method_trans "direct link")
  
  See primary documentation
  [in context](/type/Str#method_trans)
  for **method trans**.
  
  ```raku
  multi method trans(Str:D: Pair:D \what, *%n --> Str)
  multi method trans(Str:D: *@changes, :complement(:$c), :squash(:$s), :delete(:$d) --> Str)
  ```
  
  Replaces one or many characters with one or many characters. Ranges are supported, both for keys and values. Regexes work as keys. In case a list of keys and values is used, substrings can be replaced as well. When called with `:complement` anything but the matched value or range is replaced with a single value; with `:delete` the matched characters without corresponding replacement are removed. Combining `:complement` and `:delete` will remove anything but the matched values, *unless replacement characters have been specified*, in which case, `:delete` would be ignored. The adverb `:squash` will reduce repeated matched characters to a single character.
  
  Example:
  
  ```raku
  my $str = 'say $x<b> && $y<a>';
  $str.=trans( '<' => '«' );
  $str.=trans( '<' => '«', '>' => '»' );
  
  $str.=trans( [ '<'   , '>'   , '&' ] =>
               [ '&lt;', '&gt;', '&amp;' ]);
  
  $str.=trans( ['a'..'y'] => ['A'..'z'] );
  
  "abcdefghij".trans(/<[aeiou]> \w/ => '');                     # OUTPUT: «cdgh»
  
  "a123b123c".trans(['a'..'z'] => 'x', :complement);            # OUTPUT: «axxxbxxxc»
  "aaa1123bb123c".trans('a'..'z' => 'A'..'Z', :squash);         # OUTPUT: «A1123B123C»
  "aaa1123bb123c".trans('a'..'z' => 'x', :complement, :squash); # OUTPUT: «aaaxbbxc»
  ```
  
  In general, the strings will have the same length after the substitution:
  
  ```raku
  say "a123b123c".trans('23' => '4');   # OUTPUT: «a144b144c␤»
  say "a123b123c".trans('123' => 'þð'); # OUTPUT: «aþðþbþðþc␤»
  ```
  
  `:squash` and `:delete` will have the same effect in this case making it a strict substitution:
  
  ```raku
  say "a123b123c".trans('123' => 'þð', :squash); # OUTPUT: «aþðbþðc␤»
  say "a123b123c".trans('123' => 'þð', :delete); # OUTPUT: «aþðbþðc␤»
  ```
  
  `:delete` will also remove non-matched characters from the original string:
  
  ```raku
  say "abc".trans("abc".comb => 1..2, :delete);  # OUTPUT: «12␤»
  ```
  
  Please note that the behavior of the two versions of the multi method is slightly different. The first form will transpose only one character if the origin is also one character:
  
  ```raku
  say "abcd".trans( "a" => "zz" );  # OUTPUT: «zbcd␤»
  say "abcd".trans( "ba" => "yz" ); # OUTPUT: «zycd␤»
  
  ```
  
  In the second case, behavior is as expected, since the origin is more than one char long. However, if the [`Pair`](/type/Pair) in the multi method does not have a `Str` as an origin or target, it is handled to the second multi method, and behavior changes:
  
  ```raku
  say "abcd".trans: ["a"] => ["zz"]; # OUTPUT: «zzbcd␤»
  ```
  
  In this case, neither origin nor target in the [`Pair`](/type/Pair) are `Str`; the method with the [`Pair`](/type/Pair) signature then calls the second, making this call above equivalent to `"abcd".trans: ["a"] => ["zz"],` (with the comma behind, making it a [`Positional`](/type/Positional), instead of a [`Pair`](/type/Pair)), resulting in the behavior shown as output.
  
  # [In Cool](#___top "go to top of document")[§](#(Cool)_method_trans "direct link")
  
  See primary documentation
  [in context](/type/Cool#method_trans)
  for **method trans**.
  
  ```raku
  method trans(|)
  ```
  
  Coerces the invocant to [`Str`](/type/Str) and calls [Str.trans](/type/Str#method_trans)
  