UnicodeLeft (Unicode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (misc formatting)
 
(36 intermediate revisions by 6 users not shown)
Line 1: Line 1:
<span style="font-size:120%; color:black"><b>Left-most characters of string to specified length</b></span>
{{Template:Unicode:UnicodeLeft subtitle}}
[[Category:Intrinsic Unicode methods|UnicodeLeft function]]
<var>UnicodeLeft</var> returns the left-most characters of the method object string, possibly padding it on the right.
[[Category:Intrinsic methods]]
[[Category:System methods]]
<!--DPL?? Category:Intrinsic Unicode methods|UnicodeLeft function: Left-most characters of string to specified length-->
<!--DPL?? Category:Intrinsic methods|UnicodeLeft (Unicode function): Left-most characters of string to specified length-->
<!--DPL?? Category:System methods|UnicodeLeft (Unicode function): Left-most characters of string to specified length-->


This function returns the left-most characters of the method object string,
==Syntax==
possibly padding it on the right.
{{Template:Unicode:UnicodeLeft syntax}}


The UnicodeLeft function is available as of version 7.5  of the ''Sirius Mods''.
===Syntax terms===
===Syntax===
<table class="syntaxTable">
  %outUni = unicode:unicodeLeft(length, [Pad=char])
<tr><th>%outUnicode</th>
====Syntax Terms====
<td>A <var>Unicode</var> variable to receive the result of the <var>UnicodeLeft</var> method. </td></tr>
<dl>
<dt><i>%outUni</i>
<dd>A Unicode variable to receive the result of the UnicodeLeft method.
<dt><i>unicode</i>
<dd>A Unicode string.
<dt><i>length</i>
<dd>The number of the left-most characters to return.
If the method object is shorter than the requested number of characters, it is either
padded to the requested length or the entire method object string is
returned with no padding, depending on the value of the Pad parameter.
<dt><b>Pad=</b><i>char</i>
<dd>The character used to pad the method object string on the right if
it is shorter than the requested length.
''char'' defaults to a null, which means no padding is done.
Pad is a name-required parameter.


</dl>
<tr><th>unicode</th>
===Usage Notes===
<td>A <var>Unicode</var> string. </td></tr>
 
<tr><th>number</th>
<td>The number of the left-most characters to return. If <var class="term">unicode</var> is shorter than the requested number of characters, it is either padded to the requested length or returned with no padding, depending on the value of the <var>Pad</var> parameter. </td></tr>
 
<tr><th><var>Pad</var></th>
<td>A single character used to pad <var class="term">unicode</var>, on the right, if it is shorter than the requested <var class="term">number</var>. <var class="term">c</var> defaults to a null string (<tt><nowiki>''</nowiki></tt>) which means no padding is done.
<p>
<var>Pad</var> is a [[Notation conventions for methods#Named parameters|name required]] parameter, and <var>Pad</var> is a <var>Unicode</var> string. Like all <var>Unicode</var> arguments, if an EBCDIC string is specified, it is, converted to <var>Unicode</var>. </p></td></tr>
</table>
 
==Usage notes==
<ul>
<ul>
<li>The ''length'' value must be a non-negative number.
<li>The <var class="term">number</var> value must be a non-negative number. A negative number results in request cancellation. </li>
A negative number results in request cancellation.
 
<li>The pad parameter value must be either null or a single character.
<li>The <var>Pad</var> parameter value must be either null or a single character. A longer value results in a compilation error. </li>
A longer value results in a compilation error.
 
<li>The UnicodeLeft method is identical to the UnicodeSubstring method
<li><var>UnicodeLeft</var> is identical to <var>[[UnicodeSubstring (Unicode function)|UnicodeSubstring]]</var> with <code>1</code> as its first argument. </li>
(??[[UnicodeSubstring (Unicode function)|UnicodeSubstring]]) with a 1 for the first argument.
 
<li>The UnicodeLeft method is analogous to
<li><var>UnicodeLeft</var> is analogous to the <var>[[Left (String function)|Left]]</var> <var>String</var> intrinsic method. </li>
the String intrinsic Left method (??[[Left (String function)|Left]]).
</ul>
</ul>
===Examples===


The following statement displays <tt>Model 2</tt>:
==Examples==
    %u is unicode initial('Model 204&amp;#x2122;':U)
<ol>
    [[Intrinsic classes#printtext|printText]] {%u:unicodeLeft(7)}
<li>The following statement displays <code>Model 2</code>:
<p class="code">%u is unicode initial('Model 204&amp;#x2122;':[[U (String function)|U]])
[[Intrinsic classes#printtext|printText]] {%u:unicodeLeft(7)}
</p>
 
<li>The following statement displays <code>Model 204!!!</code>:
<p class="code">%u is unicode initial('Model 204')
printText {%u:unicodeLeft(12, pad='!')}
</p>


The following statement displays <tt>Model 204!!!</tt>:
<li>The following statement gets a character translation exception because the <var>Unicode</var> character <code>&amp;#x2122;</code> (trademark) has no EBCDIC equivalent:
<pre>
<p class="code">%u is unicode initial('Model 204&amp;#x2122;':U)
    %u is unicode initial('Model 204')
printText {%u:unicodeLeft(10)}
    printText {%u:unicodeLeft(12, pad='!')}
</p></ol>
</pre>


The following statement gets a character translation exception
==See also==
because the Unicode character <tt>&amp;#x2122;</tt> (trademark) has no
{{Template:Unicode:UnicodeLeft footer}}
Ebcdic equivalent:
<pre>
    %u is unicode initial('Model 204&amp;#x2122;':U)
    printText {%u:unicodeLeft(10)}
</pre>

Latest revision as of 18:31, 11 July 2017

The left-most characters of the string (Unicode class)

UnicodeLeft returns the left-most characters of the method object string, possibly padding it on the right.

Syntax

%outUnicode = unicode:UnicodeLeft( number, [Pad= c])

Syntax terms

%outUnicode A Unicode variable to receive the result of the UnicodeLeft method.
unicode A Unicode string.
number The number of the left-most characters to return. If unicode is shorter than the requested number of characters, it is either padded to the requested length or returned with no padding, depending on the value of the Pad parameter.
Pad A single character used to pad unicode, on the right, if it is shorter than the requested number. c defaults to a null string ('') which means no padding is done.

Pad is a name required parameter, and Pad is a Unicode string. Like all Unicode arguments, if an EBCDIC string is specified, it is, converted to Unicode.

Usage notes

  • The number value must be a non-negative number. A negative number results in request cancellation.
  • The Pad parameter value must be either null or a single character. A longer value results in a compilation error.
  • UnicodeLeft is identical to UnicodeSubstring with 1 as its first argument.
  • UnicodeLeft is analogous to the Left String intrinsic method.

Examples

  1. The following statement displays Model 2:

    %u is unicode initial('Model 204&#x2122;':U) printText {%u:unicodeLeft(7)}

  2. The following statement displays Model 204!!!:

    %u is unicode initial('Model 204') printText {%u:unicodeLeft(12, pad='!')}

  3. The following statement gets a character translation exception because the Unicode character &#x2122; (trademark) has no EBCDIC equivalent:

    %u is unicode initial('Model 204&#x2122;':U) printText {%u:unicodeLeft(10)}

See also