View source for UnicodeSubstring (Unicode function)

{{Template:Unicode:UnicodeSubstring subtitle}}

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

==Syntax==
{{Template:Unicode:UnicodeSubstring syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>%outUnicode</th>
<td>A <var>Unicode</var> variable to receive the result of the <var>UnicodeSubstring</var> method. </td></tr>

<tr><th>unicode</th>
<td>A <var>Unicode</var> string. </td></tr>

<tr><th>position</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>

<tr><th>length</th>
<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>

==Usage notes==
<ul>
<li>The <var class="term">length</var> must be a non-negative number.  A negative <var class="term">length</var> 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>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>.
<li><var>UnicodeSubstring</var> is available as of <var class="product">Sirius Mods</var> Version 7.5.
</ul>

==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>

<li>The following statement displays <code>C?!</code>:
<p class="code">%u is unicode initial('ABC&amp;#xA1;':[[U (String function)|U]])
[[Intrinsic classes#printtext|printText]] {%u:unicodeSubstring(3,3, pad='!')}
</p>
The question mark in the result represents a valid EBCDIC character that is not displayable.
</ol>

==See also==
<ul>
<li><var>UnicodeSubstring</var> is analogous to the intrinsic <var>[[String class|String]]</var> method: <var>[[Substring (String function)|Substring]]</var>.</ul>

{{Template:Unicode:UnicodeSubstring footer}}