SUBSTR()
 Extract a substring from a character string
------------------------------------------------------------------------------
 Syntax

     SUBSTR(<cString>, <nStart>, [<nCount>]) --> cSubstring

 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
     Clipper.

     <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.

 Returns

     SUBSTR() returns a character string.

 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.

 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

 Files   Library is CLIPPER.LIB.

See Also: RAT() RIGHT() STR()