Substring (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
 
(35 intermediate revisions by 4 users not shown)
Line 1: Line 1:
This [[Intrinsic classes|intrinsic]] function returns a specific number of bytes starting at a         
{{Template:String:Substring subtitle}}
specific position in the method object string, possibly padding it on the right.                       
                                                                                                       
Substring is available as of version 7.2 of the [[Sirius Mods]].                                       
===Substring syntax===                                                                                 
  %outStr = string:substring(start, [length] [, Pad=char])                                           
===Syntax Terms===                                                                                     
<dl>                                                                                                   
<dt>%outStr                                                                                           
<dd>A variable to receive the string result of the Substring method.                                   
<dt>string                                                                                             
<dd>The input string or Longstring.                                                                   
<dt>start                                                                                             
<dd>The byte number 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 byte number ''''1''''.                       
<dt>length                                                                                             
<dd>An optional, numeric value that is the number of bytes to return.                                 
If the method object has fewer characters than the requested bytes                                     
(starting at the start position), it is either padded to the requested                                 
length, or the entire method object string starting at the start position                             
is returned with no padding, depending on the value of the pad parameter.                             
                                                                                                       
If you do not specify a ''length'' value,                                                             
Substring returns everything in the method object string from the ''start''                           
byte to the end of the string.                                                                         
<dt>Pad=char                                                                                           
<dd>The character used to pad the result string on the right if it's shorter than the requested length.
''char'' defaults to a null, which means no padding is done. Pad is a name-required parameter.         
                                                                                                       
</dl>                                                                                                 
===Usage Notes===
*The length must be a non-negative number. A negative number results in request cancellation.
*The pad parameter must be either null or a single character. A longer value results in request cancellation in [[Sirius Mods]] version 7.2 and in a compilation error in [[Sirius Mods]] 7.3 and higher.         
*If the starting position is known to be 1, it might be tidier and slightly more efficient to use the Left method instead of Substring.
===Examples===                                                                             
*The following statement places into %y the 5 bytes of %x starting at the third byte. If %x is shorter than 7 bytes, then all of %x is copied into %y:     
    %y = %x:substring(3, 5)                                                                 
*The following statement displays ''''psi'''':                                             
    [[Intrinsic classes#printtext|printText]] {'Ypsilanti':substring(2, 3)}                         
                                                                                           
*The following request displays '''''123456':substring(3) = 3456'''':                       
    b                                                                                       
    printText {~} = {'123456':substring(3)}                                                
    end


===See also===                                                                             
The <var>Substring</var> [[Intrinsic classes|intrinsic]] function returns a specific number of bytes starting at a specific position in the method object string, possibly padding it on the right.
[[List of intrinsic String methods]]


[[Category:Intrinsic String methods|Substring function]]
==Syntax==
[[Category:Intrinsic methods]]
{{Template:String:Substring syntax}}
 
===Syntax terms===
<table class="syntaxTable">
<tr><th>%outString</th>
<td>A variable to receive the string result of the <var>Substring</var> method.</td></tr>
 
<tr><th>string</th>
<td>The input method object string</td></tr>
 
<tr><th>position</th>
<td>The byte number in the method object <var class="term">string</var> that is the starting point of the substring that is returned.  The first character from the left in the method object <var class="term">string</var> is always byte number <b><i>1</i></b>.</td></tr>
 
<tr><th>length</th>
<td>An optional, numeric value that is the number of bytes to return.  If the method object <var class="term">string</var> has fewer characters than the requested bytes (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 <var class="term">string</var> starting at the start <var class="term">position</var> is returned with no padding, depending on the value of the <var>Pad</var> parameter. If you do not specify a <var class="term">length</var> value, <var>Substring</var> returns everything in the method object <var class="term">string</var> from the <var class="term">position</var> character to the end of the string.</td></tr>
 
<tr><th><var>Pad</var></th>
<td>This is an optional, [[Notation conventions for methods#Named parameters|name required]], parameter that specifies the character used to pad the result string on the right, if it is shorter than the requested <var class="term">length</var>. <var>Pad</var> defaults to the null string, which means no padding is done.</td></tr>
</table>
 
==Usage notes==
<ul><li>The <var class="term">length</var> must be a non-negative number. 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 request cancellation in <var class="product">Sirius Mods</var> Version 7.2 and in a compilation error in <var class="product">Sirius Mods</var> Version 7.3 and higher.
<li>If the starting position is known to be 1, it might be tidier and slightly more efficient to use the Left method instead of <var>Substring</var>.
<li><var>Substring</var> is available as of <var class="product">[[Sirius Mods|Sirius Mods]]</var> Version 7.2.</ul>
 
==Examples==
<ol><li>The following statement places into %y the 5 bytes of %x starting at the third byte. If %x is shorter than 7 bytes, then all of %x is copied into %y:
<p class="code">%y = %x:substring(3, 5)
</p>
<li>The following statement displays <code>'psi'</code>:
<p class="code">[[PrintText statement|printText]] {'Ypsilanti':substring(2, 3)}
</p>
<li>The following request displays <code>'123456':substring(3) = 3456</code>:
<p class="code">begin
  printText {~} = {'123456':substring(3)}
end
</p></ol>
 
==See also==
{{Template:String:Substring footer}}

Latest revision as of 22:04, 7 August 2012

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


The Substring intrinsic function returns a specific number of bytes starting at a specific position in the method object string, possibly padding it on the right.

Syntax

%outString = string:Substring( position, [length], [Pad= c])

Syntax terms

%outString A variable to receive the string result of the Substring method.
string The input method object string
position The byte number in the method object string that is the starting point of the substring that is returned. The first character from the left in the method object string is always byte number 1.
length An optional, numeric value that is the number of bytes to return. If the method object string has fewer characters than the requested bytes (starting at the position), it is either padded to the requested length, or the entire method object string starting at the start position is returned with no padding, depending on the value of the Pad parameter. If you do not specify a length value, Substring returns everything in the method object string from the position character to the end of the string.
Pad This is an optional, name required, parameter that specifies 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.

Usage notes

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

Examples

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

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

  2. The following statement displays 'psi':

    printText {'Ypsilanti':substring(2, 3)}

  3. The following request displays '123456':substring(3) = 3456:

    begin printText {~} = {'123456':substring(3)} end

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Substring_(String_function)&oldid=1736"