5.1.7.95. translate

Returns a copy of the receiving string with each character translated to another character or unchanged. You can also use this method to reorder the characters in the output table. (See last example)

The output table is tableo and the input translation table is tablei. translate searches tablei for each character in the receiving string. If the character is found, the corresponding character in tableo is used in the result string. If there are duplicates in tablei, the first (leftmost) occurrence is used. If the character is not found, the original character in the receiving string is used. The result string is always of the same length as the receiving string.

The tables can be of any length. If you specify neither translation table and omit pad, the receiving string is translated to uppercase (that is, lowercase a-z to uppercase A-Z), but if you include pad the entire string is translated to pad characters. tablei defaults to XRANGE("00"x,"FF"x), and tableo defaults to the null string and is padded with pad or truncated as necessary. The default pad is a blank.

n is the position of the first character of the translated range. The default starting position is 1. length is the range of characters to be translated. If length is omitted, the remainder of the string from the starting position to the end is used.

Example 5.130. String class — translate method

"abcdef"~translate                         -->    "ABCDEF"
"abcdef"~translate(, , , 3, 2)             -->    "abCDef"
"abcdef"~translate("12", "ec")             -->    "ab2d1f"
"abcdef"~translate("12", "abcd", ".")      -->    "12..ef"
"APQRV"~translate(, "PR")                  -->    "A Q V"
"APQRV"~translate(XRANGE("00"X, "Q"))      -->    "APQ  "
"4123"~translate("abcd", "1234", , 2, 2)   -->    "4ab3"
"4123"~translate("abcd", "1234")           -->    "dabc"

Note

The last example shows how to use the translate method to reorder the characters in a string. In the example, the last character of any 4-character string specified as the first argument would be moved to the beginning of the string.