UnicodeSubstring (Unicode function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
 
(18 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:Unicode:UnicodeSubstring subtitle}}
{{Template:Unicode:UnicodeSubstring subtitle}}
[[Category:Unicode methods|UnicodeSubstring function]]
[[Category:Intrinsic methods]]
<!--DPL?? Category:<var>Unicode</var> methods|<var>UnicodeSubstring</var> function: Substring at specifed of string to specified length-->
<!--DPL?? Category:Intrinsic methods|<var>UnicodeSubstring</var> (<var>Unicode</var> function): Substring at specifed of string to specified length-->
<!--DPL?? Category:<var>System</var> methods|<var>UnicodeSubstring</var> (<var>Unicode</var> function): Substring at specifed of string to specified length-->


This function returns a specific number of characters starting at a
<var>UnicodeSubstring</var> returns a specific number of characters, starting at a specific position, from the method object <var>Unicode</var> string, possibly padding it on the right.
specific position in the method object <var>Unicode</var> string,
possibly padding it on the right.


The <var>UnicodeSubstring</var> function is available as of version 7.5  of the <var class=product>Sirius Mods</var>.
==Syntax==
==Syntax==
{{Template:Unicode:UnicodeSubstring syntax}}
{{Template:Unicode:UnicodeSubstring syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th><i>%outUni</i></th>
<tr><th>%outUnicode</th>
<td>A <var>Unicode</var> variable to receive the result of the <var>UnicodeSubstring</var> method. </td></tr>
<td>A <var>Unicode</var> variable to receive the result of the <var>UnicodeSubstring</var> method. </td></tr>
<tr><th><i>unicode</i></th>
 
<tr><th>unicode</th>
<td>A <var>Unicode</var> string. </td></tr>
<td>A <var>Unicode</var> string. </td></tr>
<tr><th><i>start</i></th>
 
<td>The character position in the method object that is the starting point of the substring that is returned. The first character from the left in the method object is position <tt>1</tt>. </td></tr>
<tr><th>position</th>
<tr><th><i>length</i></th>
<td>The character position in the method object that is the starting point of the substring that is returned. The first character from the left in the method object is position <code>1</code>.</td></tr>
<td>The number of characters to return. If the method object has fewer characters than the requested number of characters (starting at the start position), it is either padded to the requested length, or the entire method object starting at the start position is returned with no padding, depending on the value of the pad parameter. </td></tr>
 
<tr><th><b>Pad=</b><i>char</i></th>
<tr><th>length</th>
<td>The character used to pad the result 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.</td></tr>
<td>The number of characters to return. If the method object has fewer characters than the requested number of characters (starting at the <var class="term">position</var>), it is either padded to the requested <var class="term">length</var>, or the entire method object starting at the <var class="term">position</var> is returned with no padding, depending on the value of the <var>Pad</var> parameter. </td></tr>
 
<tr><th><var>Pad</var></th>
<td>The character used to pad the result string on the right if it is shorter than the requested length. <var>Pad</var> defaults to the null string (<tt><nowiki>''</nowiki></tt>), which means no padding is done. <var>Pad</var> is a [[Notation conventions for methods#Named parameters|name required]] parameter.</td></tr>
</table>
</table>
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>The length must be a non-negative number.
<li>The <var class="term">length</var> must be a non-negative number. A negative <var class="term">length</var> results in request cancellation.
A negative number results in request cancellation.
<li>The <var>Pad</var> parameter must be either null or a single character. A longer value results in a compilation error.
<li>The pad parameter must be either null or a single character.
<li>If the starting <var class="term">position</var> is known to be 1, it might be tidier and slightly more efficient to use the <var>UnicodeLeft</var> method instead of <var>UnicodeSubstring</var>.
A longer value results in a compilation error.
<li><var>UnicodeSubstring</var> is available as of <var class="product">Sirius Mods</var> Version 7.5.
<li>If the starting position is known to be 1, it might be tidier and
slightly more efficient to use the <var>Unicode</var>Left method instead of <var>UnicodeSubstring</var>.
<li>The <var>UnicodeSubstring</var> method is analogous to
the <var>String</var> intrinsic [[Substring (String function)|Substring]] method.
</ul>
</ul>
==Examples==
==Examples==
<ol>
<li>The following statement places into <code>%y</code> the 5 characters of <code>%x</code> starting at the third character.  If <code>%x</code> is shorter than 7 characters, then all of <code>%x</code> is copied into <code>%y</code>:
<p class="code">%y = %x:unicodeSubstring(3, 5)
</p>


The following statement places into %y the 5 characters of %x starting at the
<li>The following statement displays <code>C?!</code>:
third character.
<p class="code">%u is unicode initial('ABC&amp;#xA1;':[[U (String function)|U]])
If %x is shorter than 7 characters, then all of %x is copied into %y:
[[Intrinsic classes#printtext|printText]] {%u:unicodeSubstring(3,3, pad='!')}
<pre>
</p>
    %y = %x:unicodeSubstring(3, 5)
The question mark in the result represents a valid EBCDIC character that is not displayable.
</pre>
</ol>


The following statement displays <tt>C?!</tt>:
==See also==
    %u is unicode initial('ABC&amp;#xA1;':U)
<ul>
    [[Intrinsic classes#printtext|printText]] {%u:unicodeSubstring(3,3, pad='!')}
<li><var>UnicodeSubstring</var> is analogous to the intrinsic <var>[[String class|String]]</var> method: <var>[[Substring (String function)|Substring]]</var>.</ul>


The question mark in the result represents a valid EBCDIC character that
{{Template:Unicode:UnicodeSubstring footer}}
is not displayable.
The U constant function used in the example is described ??[[U (String function)|U]].
For information about the PrintText statement, see the list
item [[??]] refid=intprnt..

Latest revision as of 17:43, 6 November 2012

Return a substring of the method object string (Unicode class)


UnicodeSubstring returns a specific number of characters, starting at a specific position, from the method object Unicode string, possibly padding it on the right.

Syntax

%outUnicode = unicode:UnicodeSubstring( position, [length], [Pad= c])

Syntax terms

%outUnicode A Unicode variable to receive the result of the UnicodeSubstring method.
unicode A Unicode string.
position The character position in the method object that is the starting point of the substring that is returned. The first character from the left in the method object is position 1.
length The number of characters to return. If the method object has fewer characters than the requested number of characters (starting at the position), it is either padded to the requested length, or the entire method object starting at the position is returned with no padding, depending on the value of the Pad parameter.
Pad The character used to pad the result string on the right if it is shorter than the requested length. Pad defaults to the null string (''), which means no padding is done. Pad is a name required parameter.

Usage notes

  • The length must be a non-negative number. A negative length results in request cancellation.
  • The Pad parameter must be either null or a single character. A longer value results in a compilation error.
  • If the starting position is known to be 1, it might be tidier and slightly more efficient to use the UnicodeLeft method instead of UnicodeSubstring.
  • UnicodeSubstring is available as of Sirius Mods Version 7.5.

Examples

  1. The following statement places into %y the 5 characters of %x starting at the third character. If %x is shorter than 7 characters, then all of %x is copied into %y:

    %y = %x:unicodeSubstring(3, 5)

  2. The following statement displays C?!:

    %u is unicode initial('ABC&#xA1;':U) printText {%u:unicodeSubstring(3,3, pad='!')}

    The question mark in the result represents a valid EBCDIC character that is not displayable.

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=UnicodeSubstring_(Unicode_function)&oldid=12131"