$Lstr_Translate

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Translate longstring

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Lstr_Translate function is Translate.

This function takes a string or longstring input and replaces characters indicated by an "input table" with corresponding characters in an "output table".

The $Lstr_Translate function accepts four arguments and returns a string result.

The first argument is an arbitrary string or longstring. This is a required argument.

The second argument is the output table; its length must be 256 or less. This is an optional argument.

The third argument is the input table; its length must be 256 or less. This is an optional argument.

The fourth argument is a string containing a single character to be used as the pad character if the input table is longer than the output table. This is an optional argument and defaults to a blank.

Syntax

%result = $Lstr_Translate(lstring, out_tbl, in_tbl, pad_char)

%result is a copy of the first argument, with selected characters replaced as specified by the output and input tables.

Usage notes

The defaults of $Lstr_Translate are:
- If only the first argument is present, the result is to translate all lowercase characters (a-z) with their uppercase equivalents (A-Z); otherwise:
- If the input table is omitted, its default is all 256 characters, in the order X'00', X'01', ... X'FF'.
- The default output table is the null string.
- If the output table is shorter than the input table, it is padded on the right with copies of the pad character.
- If a character is specified more than once in the input table, only the first occurrence is used.
Carefully examine the examples below to understand the consequences of these defaults; for example, note in the first example that if a pad character (argument four) is specified but neither input nor output table is, then the default input table is all byte values (X'00' - X'FF') and the default output table is the null string padded to the length of the input table (256) with pad characters, resulting in a copy of the first argument with every character replaced by the pad character.

Examples

Pad char specified but no tables, input replaced by all pad chars:
PRINT $Lstr_Translate('pqrst', , , '?')

Result: ?????
Pad char specified or not and null output table only, input replaced by all pad chars:
PRINT $X2C($Lstr_Translate('pqrst', ''))

Result: 4040404040
Simple translation, input and output table arguments the same length:
PRINT $Lstr_Translate('pqrstu', '+!', 'tq')

Result: p!rs+u
Upcase:
PRINT $Lstr_Translate('pqrst')

Result: PQRST

Except for the "upcase" case, note that an omitted output table is the same as a null string output table, and that an omitted input table is the same as all 256 byte values, in order (X'00'-X'FF').
Tables identical (even both null strings), input string unchanged:
PRINT $Lstr_Translate('pqrst', '', '')

Result: pqrst
Input table longer, pad character appended to output table:
PRINT $Lstr_Translate('pqrstu', '+!', 'purt', '?')

Result: +q?s?!
Same case as preceding example, but using default pad character (blank):
PRINT $Lstr_Translate('pqrst', '', 'qs')

Result: p r t
Pad character or output table specified, default input table is X'000102...':
%S = $Lstr_Translate('pqr WITH $X2C(00)', 'xyz') PRINT '/' %S '/' WITH $C2X(%S)

Result: / x/404040A7
Same case as preceding, but using different fourth input character and output table:
%S = $Lstr_Translate('pqr WITH $X2C(40)', - $PAD(, , 63) WITH 'xyz') PRINT '/' %S '/' WITH $C2X(%S)

Result: / y/404040A8
Note that previous cases differ from null string input table, which always causes input string unchanged:
%S = $Lstr_Translate('pqr WITH $X2C(40)', - $PAD(, , 63) WITH 'xyz', '') PRINT '/' %S '/' WITH $C2X(%S)

Result: /pqr /97989940
Using any disjoint set of n characters as argument 1 and 3 lets you re-order an n character argument 2:
PRINT $Lstr_Translate('312', 'pqr', '123')

Result: rpq

Error conditions

- Omitted first argument: Request is cancelled - Either table longer than 256 bytes: Request is cancelled - Pad character not 1 byte long: Request is cancelled

Products authorizing $Lstr_Translate