$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

• Sirius functions
• Fast/Unload User Language Interface
• Janus Open Client
• Janus Open Server
• Janus Sockets
• Janus Web Server
• Japanese functions
• Sir2000 Field Migration Facility