$Lstr Translate: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
(Automatically generated page update)
 
(28 intermediate revisions by 4 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Translate longstring</span>
<span class="pageSubtitle">Translate longstring</span>


<p class="warning">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)]].</p>
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Lstr_Translate function is <var>[[Translate (String function)|Translate]]</var>.</p>


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


==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" />%result = $Lstr_Translate(lstring, out_tbl, in_tbl, pad_char)
<p class="syntax"><span class="term">%result</span> = $Lstr_Translate(lstring, out_tbl, in_tbl, pad_char)
<section end="syntax" /></p>
<p class="caption">$Lstr_Translate function
</p>
</p>
<p class="caption">%RESULT is a copy of the first argument, with selected characters replaced as specified by the output and input tables.</p>


The defaults of <var>$Lstr_Translate</var> are:
<p><var class="term">%result</var> is a copy of the first argument, with selected characters replaced as specified by the output and input tables.</p>
 
==Usage notes==
<ul>
<li>The defaults of <var>$Lstr_Translate</var> are:


<ul>
<ul>
Line 33: Line 34:
</ul>
</ul>


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.  
<li>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.  
</ul>


===Examples===  
===Examples===  
<ol>
<li>Pad char specified but no tables, input replaced by all pad chars:


Pad char specified but no tables, input replaced by all pad chars:
<p class="code">PRINT $Lstr_Translate('pqrst', , , '?')
 
</p>
<p class="code"> PRINT $Lstr_Translate('pqrst', , , '?')
<p>Result: <code>?????</code>
-> ?????
</p>
</p>


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


<p class="code"> PRINT $X2C($Lstr_Translate('pqrst', ''))
<p class="code">PRINT $X2C($Lstr_Translate('pqrst', &apos;&apos;))
-> 4040404040
</p>
<p>Result: <code>4040404040</code>
</p>
</p>


Simple translation, input &amp; output table args same length:
<li>Simple translation, input and output table arguments the same length:


<p class="code"> PRINT $Lstr_Translate('pqrstu', '+!', 'tq')
<p class="code">PRINT $Lstr_Translate('pqrstu', '+!', 'tq')
-> p!rs+u
</p>
<p>Result: <code>p!rs+u</code>
</p>
</p>


Upcase:
<li>Upcase:


<p class="code"> PRINT $Lstr_Translate('pqrst')
<p class="code">PRINT $Lstr_Translate('pqrst')
-> PQRST
</p>
<p>Result: <code>PQRST</code>
</p>
</p>


Except for the "upcase&amp;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').  
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:
<li>Tables identical (even both null strings), input string unchanged:


<p class="code"> PRINT $Lstr_Translate('pqrst', '', '')
<p class="code">PRINT $Lstr_Translate('pqrst', &apos;&apos;, &apos;&apos;)
-> pqrst
</p>
<p>Result: <code>pqrst</code>
</p>
</p>


Input table longer, pad char appended to output table:
<li>Input table longer, pad character appended to output table:


<p class="code"> PRINT $Lstr_Translate('pqrstu', '+!', 'purt', '?')
<p class="code">PRINT $Lstr_Translate('pqrstu', '+!', 'purt', '?')
-> +q?s?!
</p>
<p>Result: <code>+q?s?!</code>
</p>
</p>


Same case, using default pad char (blank):
<li>Same case as preceding example, but using default pad character (blank):


<p class="code"> PRINT $Lstr_Translate('pqrst', '', 'qs')
<p class="code">PRINT $Lstr_Translate('pqrst', &apos;&apos;, 'qs')
-> p r t
</p>
<p>Result: <code>p r t</code>
</p>
</p>


Pad char or output table specified, default input table is X'000102...':
<li>Pad character or output table specified, default input table is X'000102...':


<p class="code"> %S = $Lstr_Translate('pqr WITH $X2C(00)', 'xyz')
<p class="code">%S = $Lstr_Translate('pqr WITH $X2C(00)', 'xyz')
PRINT '/' %S '/' WITH $C2X(%S)
PRINT '/' %S '/' WITH $C2X(%S)
-> / x/404040A7
</p>
<p>Result: <code>/ x/404040A7</code>
</p>
</p>


Same case, using different 4th input char &amp; output table:
<li>Same case as preceding, but using different fourth input character and output table:


<p class="code"> %S = $Lstr_Translate('pqr WITH $X2C(40)', -
<p class="code">%S = $Lstr_Translate('pqr WITH $X2C(40)', -
$PAD(, , 63) WITH 'xyz')
$PAD(, , 63) WITH 'xyz')
PRINT '/' %S '/' WITH $C2X(%S)
PRINT '/' %S '/' WITH $C2X(%S)
-> / y/404040A8
</p>
<p>Result: <code>/ y/404040A8</code>
</p>
</p>


Note previous cases differ from null string input table, which always causes input string unchanged:
<li>Note that previous cases differ from null string input table, which always causes input string unchanged:


<p class="code"> %S = $Lstr_Translate('pqr WITH $X2C(40)', -
<p class="code">%S = $Lstr_Translate('pqr WITH $X2C(40)', -
$PAD(, , 63) WITH 'xyz', '')
$PAD(, , 63) WITH 'xyz', &apos;&apos;)
PRINT '/' %S '/' WITH $C2X(%S)
PRINT '/' %S '/' WITH $C2X(%S)
-> /pqr /97989940
</p>
<p>Result: <code>/pqr /97989940</code>
</p>
</p>


Using any disjoint set of <i>n</i> chars as arg 1 and 3 lets you re-order an <i>n</i> char arg 2:
<li>Using any disjoint set of <i>n</i> characters as argument 1 and 3 lets you re-order an <i>n</i> character argument 2:


<p class="code"> PRINT $Lstr_Translate('312', 'pqr', '123')
<p class="code">PRINT $Lstr_Translate('312', 'pqr', '123') </p>
-> rpq
<p>Result: <code>rpq</code>
</p>
</p>
</ol>


<p class="code">  
===Error conditions===
- Omitted first argument: Request is cancelled
<p class="code">- Omitted first argument: Request is cancelled
- Either table longer than 256 bytes: Request is cancelled
- Either table longer than 256 bytes: Request is cancelled
- Pad character not 1 byte long: Request is cancelled
- Pad character not 1 byte long: Request is cancelled
</p>
<p class="caption">$LIST_TRANSLATE Error Conditions
</p>
</p>


<var>$Lstr_Translate</var> is only available in <var class="product">[[Sirius Mods]]</var> Version 6.5 and later.


<p class="code">
==Products authorizing {{PAGENAMEE}}==
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[Sirius functions]]</li>
<li>[[List of $functions|Sirius functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Janus Open Client]]</li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
<li>[[Janus Open Server]]</li>
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Japanese functions]]</li>
<li>Japanese functions</li>
<li>[[Sir2000 Field Migration Facility]]</li>
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>
</ul>
</ul>
</p>
<p class="caption">Products authorizing $Lstr_Translate
</p>


[[Category:$Functions|$Lstr_Translate]]
[[Category:$Functions|$Lstr_Translate]]

Latest revision as of 22:52, 20 September 2018

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