$Lstr_Translate

Translate longstring

Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Lstr_Translate function is the Translate (String function).

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

<section begin="syntax" /> %RESULT = $Lstr_Translate(lstring, out_tbl, in_tbl, pad_char) <section end="syntax" />

$Lstr_Translate function

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

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', , , '?') -> ?????

Pad char specified or not and null output table only, input replaced by all pad chars:

PRINT $X2C($Lstr_Translate('pqrst', )) -> 4040404040

Simple translation, input & output table args same length:

PRINT $Lstr_Translate('pqrstu', '+!', 'tq') -> p!rs+u

Upcase:

PRINT $Lstr_Translate('pqrst') -> PQRST

Except for the "upcase&CQ. 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', , ) -> pqrst

Input table longer, pad char appended to output table:

PRINT $Lstr_Translate('pqrstu', '+!', 'purt', '?') -> +q?s?!

Same case, using default pad char (blank):

PRINT $Lstr_Translate('pqrst', , 'qs') -> p r t

Pad char or output table specified, default input table is X'000102...':

%S = $Lstr_Translate('pqr WITH $X2C(00)', 'xyz') PRINT '/' %S '/' WITH $C2X(%S) -> / x/404040A7

Same case, using different 4th input char & output table:

%S = $Lstr_Translate('pqr WITH $X2C(40)', - $PAD(, , 63) WITH 'xyz') PRINT '/' %S '/' WITH $C2X(%S) -> / y/404040A8

Note 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) -> /pqr /97989940

Using any disjoint set of n chars as arg 1 and 3 lets you re-order an n char arg 2:

PRINT $Lstr_Translate('312', 'pqr', '123') -> rpq

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

$LIST_TRANSLATE Error Conditions

$Lstr_Translate is only available in Sirius Mods Version 6.5 and later.

Products authorizing $Lstr_Translate

$Lstr_Translate

Syntax

Examples

Navigation menu