Skip to content

$ZTRanslate()

$ZTRanslate()

Returns a byte sequence that results from replacing or dropping bytes in the first of its arguments as specified by the patterns of its other arguments.

The format for the $ZTRANSLATE() function is:

$ZTR[ANSLATE](expr1[,expr2[,expr3]])

  • The first expression specifies the sequence of octets on which $ZTRANSLATE() operates. If the other arguments are omitted, $ZTRANSLATE() returns this expression.

  • The optional second expression specifies the byte for $TRANSLATE() to replace. If a byte occurs more than once in the second expression, the first occurrence controls the translation, and $ZTRANSLATE() ignores subsequent occurrences. If this argument is omitted, $ZTRANSLATE() returns the first expression without modification.

  • The optional third expression specifies the replacement bytes for the positionally corresponding bytes in the second expression. If this argument is omitted or shorter than the second expression, $ZTRANSLATE() drops all occurrences of the bytes 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. $ZTRANSLATE() continues until it encounters a byte 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, $ZTRANSLATE() operates in the standard fashion.

  • $ZTRANSLATE() provides a tool for tasks such as encryption.

The $ZTRANSLATE() algorithm can be understood as follows:

  • $ZTRANSLATE() evaluates each byte in the first expression, comparing it byte by byte to the second expression looking for a match. If there is no match in the second expression, the resulting expression contains the byte without modification.
  • When it locates a byte match, $ZTRANSLATE() 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 bytes than the third expression, $ZTRANSLATE() replaces the original byte with a null, thereby deleting it from the result. By extension of this principle, if the third expression is missing, $ZTRANSLATE() deletes all bytes from the first expression that occur in the second expression.

Examples of $ZTRANSLATE()

Example:

GTM>set hiraganaA=$char(12354) ; $zchar(227,129,130) 
GTM>set temp1=$zchar(130)
GTM>set temp2=$zchar(140)
GTM>set tr=$ztranslate(hiraganaA,temp1,temp2)
GTM>w $ascii(tr)
12364 
GTM>

In the above example, $ZTRANSLATE() replaces byte $ZCHAR(130) in first expression and matching the first (and only) byte in the second expression with byte $ZCHAR(140) - the corresponding byte in the third expression.