SUBSTR()
 Extrai um substring de uma cadeia de caracteres
------------------------------------------------------------------------------

 Sintaxe

     SUBSTR(<cString>, <nInício>, [<nCont>]) --> cSubstring

 Argumentos

     <cString> é a cadeia de caracteres da qual será extraido um
     substring, podendo ter até 65.535 (64K) bytes, que é o tamanho máximo
     de uma cadeia de caracteres em Clipper.

     <nInício> é a posiçao inicial em <cString>.  Se <nInício> for
     positivo, ele é relativo ao caractere mais à esquerda em <cString>.  Se
     <nInício> for negativo, ele é relativo ao caractere mais à direita em
     <cString>.

     <nCont> é a quantidade de caracteres a serem extraidos.  Se
     omitido, o substring começa em <nInício> e continua até o fim da cadeia
     de caracteres.  Se <nCont> for maior do que a quantidade de caracteres
     existentes a partir de <nInício> até o final de <cString>, o excedente
     é ignorado.

 Retorno

     SUBSTR() retorna uma cadeia de caracteres.

 Descriçao

     SUBSTR() é uma funçao de tratamento de caracteres que extrai um
     substring de qualquer outra cadeia ou campo memo.  SUBSTR() está
     relacionada às funçoes LEFT() e RIGHT(), que extraem substrings que
     começam com os caracteres mais à esquerda e mais à direita em
     <cString>, respectivamente.

     As funçoes SUBSTR(), RIGHT(), e LEFT() sao utilizadas juntamente com as
     funçoes AT() e RAT() para localizar a primeira e/ou última posiçao de
     um substring antes de extrai-lo.  Elas também sao utilizadas para
     exibir ou imprimir apenas uma parte de uma cadeia de caracteres.

 Exemplos

       Os exemplos a seguir extraem o primeiro e o último nome de
        uma variável:

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

       Este exemplo utiliza SUBSTR() juntamente com AT() e RAT()
        para criar uma funçao definida pelo usuário com a finalidade de
        extrair um nome de arquivo de uma especificaçao dada:

        ? FileBase("C:\PRG\MYFILE.OBJ")            // Resulta: 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

 Arquivos:  Biblioteca CLIPPER.LIB.
 To download this example - click here.

See Also: AT() LEFT() RAT() RIGHT()