STUFF()
 Elimina e insere caracteres em um string
------------------------------------------------------------------------------

 Sintaxe

     STUFF(<cString>, <nInício>,
        <nElimina>, <cInsere>) --> cNovoString

 Argumentos

     <cString> é a cadeia de caracteres destino na qual serao eliminados
     e inseridos caracteres.

     <nInício> é a posiçao inicial na cadeia de caracteres destino onde
     ocorre a inserçao/eliminaçao.

     <nElimina> é a quantidade de caracteres a serem eliminados.

     <cInsere> é a cadeia de caracteres a ser inserida.

 Retorno

     STUFF() retorna uma cópia de <cString>, sendo que os caracteres
     especificados foram eliminados e <cInsere> inserida.

 Descriçao

     STUFF() é uma funçao de tratamento de caracteres que elimina <nElimina>
     caracteres de <cString> a partir da posiçao <nInício>.  Depois, ela
     insere <cInsere> na cadeia de caracteres resultante a partir de
     <nInício>, para a formar a cadeia de caracteres a ser retornada.  Desta
     forma, a funçao STUFF() pode realizar as seis operaçoes a seguir:

       Inserçao: Se <nElimina> for zero, nenhum caractere é
        removido de <cString>.  <cInserçao> é depois inserido em <nInício>,
        e a cadeia de caracteres inteira é retornada.  Por exemplo,
        STUFF("Meu gato tem pulgas.", 10, 0, "nao ") retorna "Meu gato nao
        tem pulgas."

       Substituiçao: Caso <cInsere> seja do mesmo tamanho que
        <nElimina>, <cInsere> substitui os caracteres a partir de
        <nInício>.  A mesma quantidade de caracteres que é eliminada é
        inserida, e a cadeia de caracteres resultante tem o mesmo tamanho da
        original.  Por exemplo, STUFF("Meu gato tem pulgas.", 14, 6,
        "lingua") retorna "Meu gato tem lingua."

       Eliminaçao: Se <cInsere> for uma cadeia de caracteres
        nula (""), a quantidade de caracteres especificada por <nElimina> é
        removida de <cString>, e é retornado o string sem que nenhum
        caractere tenha sido adicionado.  Por exemplo, STUFF("Meu gato tem
        pulgas.", 1, 4, "") retorna "gato tem pulgas."

       Substituiçao e inserçao: Caso <cInsere> seja maior do que
        <nElimina>, todos os caracteres, desde <nInício> até <nElimina>, sao
        substituidos, e o resto de <cInsere> é inserido.  Como há mais
        caracteres a serem inseridos do que a serem eliminados, a cadeia de
        caracteres resultante é sempre maior do que a original.  Por
        exemplo, STUFF("Meu gato tem pulgas.", 10, 3, "possui") retorna "Meu
        gato possui pulgas."

       Substituiçao e eliminaçao: Se o tamanho de <cInsere> for
        menor o que <nElimina>, há mais caracteres a serem eliminados do que
        inseridos.  A cadeia de caracteres resultante, portanto, é menor do
        que a original.  Por exemplo, STUFF("Meu gato possui pulgas.", 10,
        3, "tem") retorna "Meu gato tem pulgas."

       Substituiçao e eliminaçao do resto: Caso <nElimina> seja
        maior ou igual à quantidade de caracteres existentes em <cString> a
        partir de <nInício>, todos os caracteres restantes sao eliminados
        antes que <cInsere> seja inserido.  Por exemplo, STUFF("Meu gato tem
        pulgas.", 10, 11, "faz.") retorna "Meu gato faz."

 Exemplos

     Os exemplos a seguir demonstram as seis operaçoes básicas de STUFF():

     // Insere
     ? STUFF("ABCDEF", 2, 0, "xyz")           // Resulta: AxyzBCDEF

     // Substitui
     ? STUFF("ABCDEF", 2, 3, "xyz")           // Resulta: AxyzEF

     // Elimina
     ? STUFF("ABCDEF", 2, 2, "")              // Resulta: ADEF

     // Substitui e insere
     ? STUFF("ABCDEF", 2, 1, "xyz")           // Resulta: AxyzCDEF

     // Substitui e elimina
     ? STUFF("ABCDEF", 2, 4, "xyz")           // Resulta: AxyzF

     // Substitui e elimina o resto
     ? STUFF("ABCDEF", 2, 10, "xyz")          // Resulta: Axyz

 Arquivos:  Biblioteca EXTEND.LIB, fonte EXAMPLEC.C.
 To download this example - click here.

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