Functions and Directives

Function At() Foundation

Determines first position of a substring within a character string.

At( <cSubString>, <cString> [,<nStartPos>] ) --> nPosition
<cSubString> is a character or a character string whose position in <cString> is determined.
<cString> is the character string searched.
The optional numeric parameter <nStartPos> defines the position within <cString> to start the search from. It defaults to 1.

At() searches the character string <cString> from the beginning (left) and returns the position of <cSubString> as an integer numeric value. When <cSubString> is not found in <cString>, the return value is zero.


The character function At() determines the first position of a character substring within another character string. <cString> is searched from the left. The counterpart of At() is the function RAt(), which searches a character string from the right (starting at the end) and determines the position of the last occurrence of a character substring within a string. The $ operator is also similar and tests whether a character substring is contained in a string.

The functions At() and RAt() are often used with the functions SubStr(), Left() and Right() to perform character string operations.

// The example shows various results of the function At(). 


   ? At("X"   , "Xbase++")                  // result: 1 
   ? At("base", "Xbase++")                  // result: 2 
   ? At("3"   , "Xbase++")                  // result: 0 

   ? At("s"   , "Xbase++", 2)               // result: 4 
   ? At("s"   , "Xbase++", 5)               // result: 0 

Extracts system paths with At() and Getenv()

// In this example the list of system paths is determined 
// using the function Getenv(). Then each individual 
// path is stored in an array element. 

FUNCTION PathList() 
   LOCAL cPathList := Getenv("PATH") 
   LOCAL nPosition, aPath := {} 

   DO WHILE ( nPosition := At(";",cPathList) ) > 0 
      AAdd( aPath, Left( cPathList, nPosition-1 ) ) 
      cPathList := SubStr( cPathList, nPosition+1 ) 
   IF Len( cPathList ) > 0 
      AAdd( aPath, cPathList ) 

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.