Function At() Foundation

Determines first position of a substring within a character string.

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

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.

Description

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.

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

PROCEDURE Main 

   ? 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 

RETURN 
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 ) 
   ENDDO 
   IF Len( cPathList ) > 0 
      AAdd( aPath, cPathList ) 
   ENDIF 
RETURN aPath 
Feedback

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.