$FUNCNAME$
  SUBSTR()
$CATEGORY$
  STRING
$SUMMARY$
   Extract a substring from a character string
$LANG_RU$
       .
$SYNTAX$
     SUBSTR(<cString>, <nStart>, [<nCount>]) --> cSubstring
$LANG_RU$
     SUBSTR(< >, < >, [<- >]) --> 
$ARGUMENTS$
     <cString> is the character string from which to extract a substring.
     It can be up to 65,535 (64K) bytes, the maximum character string size in
     xClipper.
     <nStart> is the starting position in <cString>.  If <nStart> is
     positive, it is relative to the leftmost character in <cString>.  If
     <nStart> is negative, it is relative to the rightmost character in the
     <cString>.
     <nCount> is the number of characters to be extracted.  If omitted,
     the substring begins at <nStart> and continues to the end of the string.
     If <nCount> is greater than the number of characters from <nStart> to
     the end of <cString>, the excess numbers are ignored.
$LANG_RU$
     < > -  ,    
      .      65 535 (64) ,
            xClipper.
     < > -    ,  
     < >.    < >
     ,        
      < >.
         < > - , 
        .
     <- > -    .  
     ,      <
     >     .   
     <- >   ,   
      < >   , 
      < >,   .
$RETURNS$
     SUBSTR() returns a character string.
$LANG_RU$
     SUBSTR()    .
$DESCRIPTION$
     SUBSTR() is a character function that extracts a substring from another
     character string or memo field.  SUBSTR() is related to the LEFT() and
     RIGHT() functions which extract substrings beginning with leftmost and
     rightmost characters in <cString>, respectively.

     The SUBSTR(), RIGHT(), and LEFT() functions are often used with both the
     AT() and RAT() functions to locate either the first and/or the last
     position of a substring before extracting it.  They are also used to
     display or print only a portion of a character string.
$LANG_RU$
     SUBSTR()     , 
            memo-.
     SUBSTR()    LEFT()  RIGHT(),  
     ,        
      < >.

      SUBSTR(), RIGHT()  LEFT()     
      AT()  RAT()     () 
         .     
            .
$EXAMPLES$

       These examples extract the first and last name from a
	variable:

	cName:= "Biff Styvesent"
	? SUBSTR(cName, 1, 4)               // Result: Biff
	? SUBSTR(cName, 6)                  // Result: Styvesent
	? SUBSTR(cName, LEN(cName) + 2)     // Result: null string
	? SUBSTR(cName, -9)                  // Result: Styvesent
	? SUBSTR(cName, -9, 3)               // Result: Sty

       This example uses SUBSTR() with AT() and RAT() to create a
	user-defined function to extract a file name from a file
	specification:

	? FileBase("C:\PRG\MYFILE.OBJ")      // Result: MYFILE.OBJ

	FUNCTION FileBase( cFile )
	   LOCAL nPos
	   IF (nPos := RAT("\", cFile)) != 0
	      RETURN SUBSTR(cFile, nPos + 1)
	   ELSEIF (nPos := AT(":", cFile)) != 0
	      RETURN SUBSTR(cFile, nPos + 1)
	   ELSE
	      RETURN cFile
	   ENDIF


$LANG_RU$

              
       :

       cName = "Biff Styvesent"
       ? SUBSTR(cName, 1, 4)                 // : Biff
       ? SUBSTR(cName, 6)                    // : Styvesent
       ? SUBSTR(cName, LEN(cName) + 2)       // :  
       ? SUBSTR(cName, -9)                   // : Styvesent
       ? SUBSTR(cName, -9, 3)                // : Sty

          SUBSTR()    AT() 
       RAT()    ,    
        :

       ? FileBase("C:\PRG\MYFILE.OBJ")       // : MYFILE.OBJ

       FUNCTION FileBase( cFile )
	  LOCAL nPos
	  IF (nPos := RAT("\", cFile)) != 0
	     RETURN SUBSTR( cFile, nPos + 1)
	  ELSEIF (nPos := AT(":", cFile)) != 0
	     RETURN SUBSTR( cFile, nPos + 1)
	  ELSE
	     RETURN cFile
	  ENDIF


$SEEALSO$
  RAT(),RIGHT(),STR(),AT(),LEFT()
$END$
