$Lstr Translate

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

1. Pad char specified but no tables, input replaced by all pad chars:

   PRINT $Lstr_Translate('pqrst', , , '?')

   Result: ?????

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

   PRINT $X2C($Lstr_Translate('pqrst', ''))

   Result: 4040404040

3. Simple translation, input and output table arguments the same length:

   PRINT $Lstr_Translate('pqrstu', '+!', 'tq')

   Result: p!rs+u

4. 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').

5. Tables identical (even both null strings), input string unchanged:

   PRINT $Lstr_Translate('pqrst', '', '')

   Result: pqrst

6. Input table longer, pad character appended to output table:

   PRINT $Lstr_Translate('pqrstu', '+!', 'purt', '?')

   Result: +q?s?!

7. Same case as preceding example, but using default pad character (blank):

   PRINT $Lstr_Translate('pqrst', '', 'qs')

   Result: p r t

8. 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

9. 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

10. 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

11. 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

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