Returns a string that results from replacing or dropping characters in the first of its arguments as specified by the patterns of its other arguments.
The format for the $TRANSLATE function is:
$TR[ANSLATE](expr1[,expr2[,expr3[,expr4]]])
The first expression specifies the string on which $TRANSLATE() operates. If the other arguments are omitted, $TRANSLATE() returns this expression.
The optional second expression specifies the characters for $TRANSLATE() to replace. If a character occurs more than once in the second expression, the first occurrence controls the translation, and $TRANSLATE() ignores subsequent occurrences. If this argument is omitted, $TRANSLATE() returns the first expression without modification.
The optional third expression specifies the replacement characters for positionally corresponding characters in the second expression. If this argument is omitted or shorter than the second expression, $TRANSLATE() drops all occurrences of characters in the second expression that have no replacement in the corresponding position of the third expression.
The optional fourth expression specifies the direction for a selective translation. $TRANSLATE() continues until it encounters a character not found in the second expression on a side of the first expression specified in the fourth expression.
-
The valid (case insensitive) values for expr4 in the four-argument form are:
"L"-- translates all consecutive characters from the beginning of the first expression.
"R"-- translates all consecutive characters from the end of the first expression.
"B"-- translates all consecutive characters from the beginning and end of the first expression.
If the fourth argument is invalid/null, $TRANSLATE() operates in the standard fashion.
For a process started in UTF-8 mode, the algorithm of $TRANSLATE() treats the string arguments as UTF-8 encoded. With VIEW "BADCHAR" enabled, $TRANSLATE() produces a run-time error when it encounters a malformed character.
Irrespective of the settings of VIEW "BADCHAR" and $ZCHSET, $ZTRANSLATE() interprets argument as a sequence of bytes (rather than a sequence of characters) and performs all byte-oriented $TRANSLATE() operations. For more information, refer to “$ZTRanslate()”.
$TRANSLATE() provides a tool for tasks such as changing case and doing encryption. For examples of case translation, refer to the ^%LCASE and ^%UCASE utility routines.
The $TRANSLATE() algorithm can be understood as follows:
$TRANSLATE() evaluates each character in the first expression, comparing it character by character to the second expression looking for a match. If there is no match in the second expression, the resulting expression contains the character without modification.
When it locates a character match, $TRANSLATE() uses the position of the match in the second expression to identify the appropriate replacement for the original expression. If the second expression has more characters than the third expression, $TRANSLATE() replaces the original character with a null, thereby deleting it from the result. By extension of this principle, if the third expression is missing, $TRANSLATE() deletes all characters from the first expression that occur in the second expression.
Example:
GTM>write $translate("ABC","CB","1")
A1
GTM>
First, $TRANSLATE() searches for "A" (the first character in the first expression, "ABC") within the second expression ("CB"). Since "A" does not exist in the second expression, it appears unchanged in the result.
Next, $TRANSLATE() searches for "B" (the second character in the first expression) within the second expression ("CB"). Because "B" holds the second position in the second expression ("CB"), $TRANSLATE() searches for the character holding the second position in the third expression. Since there is no second character in the third expression, $TRANSLATE() replaces "B" with a null, effectively deleting it from the result.
Finally, $TRANSLATE() searches for "C" (the third character in the first expression) within the second expression ("CB"), finds it in the first position, and replaces it with the number 1, which is in the first position of the third expression. The translated result is "A1."
![[Note]](images/note.jpg) |
Note |
|---|---|
While this example provides an explanation for the work done by $TRANSLATE(), it does not necessarily correspond to how GT.M implements $TRANSLATE(). |
Example:
GTM>write $translate("A","AA","BC")
B
GTM>
This $TRANSLATE() example finds the first occurrence of "A" in the second expression, which holds the first character position, and substitutes the character in the first position of the third expression.
Example:
GTM>write $translate("BACKUP","AEIOU")
BCKP
GTM>
Because the $TRANSLATE() has only two parameters in this example, it finds the characters in the first expression that also exist in the second expression and deletes them from the result.
Example:
GTM>write $translate("ENCYCLOPEDIA","AEIOU","","L")
NCYCLOPEDIA
GTM>write $translate("ENCYCLOPEDIA","AEIOU","","R")
ENCYCLOPED
GTM>write $translate("ENCYCLOPEDIA","AEIOU","","B")
NCYCLOPED
GTM>
This $TRANSLATE() example has four parameters, it finds the first occurrence of 'E' from the left and first occurrence of 'I' and 'A' from the right, and deletes(because the third parameter is null/empty) them from the result.