From m204wiki
Jump to navigation Jump to search

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.


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


  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