Substring (String function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 1: Line 1:
{{Template:String:Substring subtitle}}
This [[Intrinsic classes|intrinsic]] function returns a specific number of bytes starting at a           
This [[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.                         
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 is available as of version 7.2 of the [[Sirius Mods]].                                         
===Substring syntax===                                                                                
==Syntax==
  %outStr = string:substring(start, [length] [, Pad=char])                                           
{{Template:String:Substring syntax}}
===Syntax Terms===                                                                                    
===Syntax terms===
<dl>                                                                                                     
<dl>                                                                                                     
<dt>%outStr                                                                                             
<dt>%outStr                                                                                             
Line 29: Line 31:
                                                                                                          
                                                                                                          
</dl>                                                                                                   
</dl>                                                                                                   
===Usage Notes===  
==Usage notes==
*The length must be a non-negative number. A negative number results in request cancellation.
*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.           
*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.  
*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===                                                                             
==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:       
*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)                                                                   
     %y = %x:substring(3, 5)                                                                   

Revision as of 05:14, 19 January 2011

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


This intrinsic function returns a specific number of bytes starting at a 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.

Syntax

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

Syntax terms

%outStr
A variable to receive the string result of the Substring method.
string
The input string or Longstring.
start
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'.
length
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.
Pad=char
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.

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':
   printText {'Ypsilanti':substring(2, 3)}                          
                                                                                            
  • The following request displays 123456':substring(3) = 3456':
   b                                                                                        
   printText {~} = {'123456':substring(3)}                                                  
   end

See also

List of intrinsic String methods