Functions and Directives

Function SubStr() Foundation

Extracts a string from a character string.

SubStr( <cString>, <nStart>, [<nCount>]) --> cSubString
<cString> is a character string expression from which a string is extracted.
<nStart> is an integer numeric value specifying the start position in <cString> where a string is extracted. When the value of <nStart> is positive, the starting position is determined relative to the beginning of the character string (counted from the left). If the value is negative, the position is relative to the end of the character string (counted from the right).
<nCount> is an integer numeric value specifying the number of characters to extract. If this argument is missing, all characters from <nStart> to the end of <cString> are extracted. When the value of <nCount> is greater than the number of characters from <nStart> to the end of <cString>, only the remaining characters are extracted.

SubStr() returns part of a character string.


The character function SubStr() extracts part of a character string starting at the position <nStart>. If <nStart> has a negative value, the starting position is counted backwards from the end of the character string.

The functions SubStr(), Left() and Right() all extract of parts of character strings and are often used with the functions At() and RAt() which determine the position of a substring within a character string.

// The example shows various results of the function SubStr() 


   ? SubStr("James Bond's BMW", 1, 5)  // result: James 
   ? SubStr("James Bond's BMW", 7)     // result: Bond's BMW 
   ? SubStr("James Bond's BMW",50)     // result: null string "" 
   ? SubStr("James Bond's BMW",-3)     // result: BMW 
   ? SubStr("James Bond's BMW",-10, 4) // result: Bond 

Change a character string list to an array

// In the example, the individual color values from the return value 
// of the function SetColor() are extracted with help from At() and 
// SubStr(). The color values are then stored in an array. 

   LOCAL aColor := ColorToArray( SetColor() ) 

   AEval( aColor, {|cColor| QOut( cColor ) } ) 


FUNCTION ColorToArray( cColor ) 
   LOCAL aColor := {}, nPosition 

   DO WHILE ( nPosition := At("," , cColor) ) > 0 
      AAdd( aColor, SubStr( cColor, 1, nPosition-1 ) ) 
      cColor := SubStr( cColor,  nPosition+1 ) 
   IF Len( cColor ) > 0 
      AAdd( aColor, cColor ) 

RETURN aColor 


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.