Transliterates all occurrences of the characters found (or not found if the /c modifier is specified) in the search list with the positionally corresponding character in the replacement list, possibly deleting some, depending on the modifiers specified. It returns the number of characters replaced or deleted. If no string is specified via the =~ or !~ operator, the $_ string is transliterated.

For sed devotees, y is provided as a synonym for tr.

If the /r (non-destructive) option is present, a new copy of the string is made and its characters transliterated, and this copy is returned no matter whether it was modified or not: the original string is always left unchanged. The new copy is always a plain string, even if the input string is an object or a tied variable.

Unless the /r option is used, the string specified with =~ must be a scalar variable, an array element, a hash element, or an assignment to one of those; in other words, an lvalue.

The characters delimitting SEARCHLIST and REPLACEMENTLIST can be any printable character, not just forward slashes. If they are single quotes (tr'SEARCHLIST'REPLACEMENTLIST'), the only interpolation is removal of \ from pairs of \\; so hyphens are interpreted literally rather than specifying a character range.

Otherwise, a character range may be specified with a hyphen, so tr/A-J/0-9/ does the same replacement as tr/ACEGIBDFHJ/0246813579/.

If the SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST must have its own pair of quotes, which may or may not be bracketing quotes; for example, tr(aeiouy)(yuoiea) or tr[+\-*/]"ABCD". This final example shows a way to visually clarify what is going on for people who are more familiar with regular expression patterns than with tr, and who may think forward slash delimiters imply that tr is more like a regular expression pattern than it actually is. (Another option might be to use tr[...][...].)

tr isn't fully like bracketed character classes, just (significantly) more like them than it is to full patterns. For example, characters appearing more than once in either list behave differently here than in patterns, and tr lists do not allow backslashed character classes such as \d or \pL, nor variable interpolation, so "$" and "@" are always treated as literals.

The allowed elements are literals plus \' (meaning a single quote). If the delimiters aren't single quotes, also allowed are any of the escape sequences accepted in double-quoted strings. Escape sequence details are in the table near the beginning of this section.

A hyphen at the beginning or end, or preceded by a backslash is also always considered a literal. Precede a delimiter character with a backslash to allow it.

The tr operator is not equivalent to the tr(1) utility. tr[a-z][A-Z] will uppercase the 26 letters "a" through "z", but for case changing not confined to ASCII, use lc, uc, lcfirst, ucfirst (all documented in perlfunc), or the substitution operator s/PATTERN/REPLACEMENT/ (with \U, \u, \L, and \l string-interpolation escapes in the REPLACEMENT portion).

Most ranges are unportable between character sets, but certain ones signal Perl to do special handling to make them portable. There are two classes of portable ranges. The first are any subsets of the ranges A-Z, a-z, and 0-9, when expressed as literal characters.

capitalizes the letters "h", "i", "j", and "k" and nothing else, no matter what the platform's character set is. In contrast, all of

do the same capitalizations as the previous example when run on ASCII platforms, but something completely different on EBCDIC ones.

The second class of portable ranges is invoked when one or both of the range's end points are expressed as \N{...}

removes from $string all the platform's characters which are equivalent to any of Unicode U+0020, U+0021, ... U+007D, U+007E. This is a portable range, and has the same effect on every platform it is run on. In this example, these are the ASCII printable characters. So after this is run, $string has only controls and characters which have no ASCII equivalents.

But, even for portable ranges, it is not generally obvious what is included without having to look things up in the manual. A sound principle is to use only ranges that both begin from, and end at, either ASCII alphabetics of equal case (b-e, B-E), or digits (1-4). Anything else is unclear (and unportable unless \N{...} is used). If in doubt, spell out the character sets in full.

Options:

    c   Complement the SEARCHLIST.
    d   Delete found but unreplaced characters.
    r   Return the modified string and leave the original string
        untouched.
    s   Squash duplicate replaced characters.

If the /d modifier is specified, any characters specified by SEARCHLIST not found in REPLACEMENTLIST are deleted. (Note that this is slightly more flexible than the behavior of some tr programs, which delete anything they find in the SEARCHLIST, period.)

If the /s modifier is specified, sequences of characters, all in a row, that were transliterated to the same character are squashed down to a single instance of that character.

If the /d modifier is used, the REPLACEMENTLIST is always interpreted exactly as specified. Otherwise, if the REPLACEMENTLIST is shorter than the SEARCHLIST, the final character, if any, is replicated until it is long enough. There won't be a final character if and only if the REPLACEMENTLIST is empty, in which case REPLACEMENTLIST is copied from SEARCHLIST. An empty REPLACEMENTLIST is useful for counting characters in a class, or for squashing character sequences in a class.

If the /c modifier is specified, the characters to be transliterated are the ones NOT in SEARCHLIST, that is, it is complemented. If /d and/or /s are also specified, they apply to the complemented SEARCHLIST. Recall, that if REPLACEMENTLIST is empty (except under /d) a copy of SEARCHLIST is used instead. That copy is made after complementing under /c. SEARCHLIST is sorted by code point order after complementing, and any REPLACEMENTLIST is applied to that sorted result. This means that under /c, the order of the characters specified in SEARCHLIST is irrelevant. This can lead to different results on EBCDIC systems if REPLACEMENTLIST contains more than one character, hence it is generally non-portable to use /c with such a REPLACEMENTLIST.

Another way of describing the operation is this: If /c is specified, the SEARCHLIST is sorted by code point order, then complemented. If REPLACEMENTLIST is empty and /d is not specified, REPLACEMENTLIST is replaced by a copy of SEARCHLIST (as modified under /c), and these potentially modified lists are used as the basis for what follows. Any character in the target string that isn't in SEARCHLIST is passed through unchanged. Every other character in the target string is replaced by the character in REPLACEMENTLIST that positionally corresponds to its mate in SEARCHLIST, except that under /s, the 2nd and following characters are squeezed out in a sequence of characters in a row that all translate to the same character. If SEARCHLIST is longer than REPLACEMENTLIST, characters in the target string that match a character in SEARCHLIST that doesn't have a correspondence in REPLACEMENTLIST are either deleted from the target string if /d is specified; or replaced by the final character in REPLACEMENTLIST if /d isn't specified.

Some examples:

If multiple transliterations are given for a character, only the first one is used:

will transliterate any A to X.

Because the transliteration table is built at compile time, neither the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote interpolation. That means that if you want to use variables, you must use an eval():