7.4.68. TRANSLATE

Returns string with each character translated to another character or unchanged. You can also use this function to reorder the characters in string.

The output table is tableo and the input translation table is tablei. TRANSLATE searches tablei for each character in 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 string is used. The result string is always the same length as string.

The tables can be of any length. If you specify neither table and omit pad, string is simply translated to uppercase (that is, lowercase a-z to uppercase A-Z), but, if you include pad, the language processor translates the entire string 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.

pos 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.

Here are some examples:

Example 7.93. Builtin function TRANSLATE

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

Note

The last example shows how to use the TRANSLATE function to reorder the characters in a string. The last character of any four-character string specified as the second argument is moved to the beginning of the string.