FUNçãOPublicado

StrTran

StrTran( <cString>, <cSearch>, [cReplace], [nStart], [nCount] ) --> cResult

Substitui ocorrências de uma sequência de caracteres dentro de uma string.

StringCaracterSubstituiçãoLimpeza de dadosFunções essenciais

01 · VISÃO GERAL

Visão geral

StrTran() é usada para localizar uma sequência de caracteres dentro de outra string e substituí-la por um novo conteúdo. Na prática, aparece muito em normalização de dados: remover pontuação de CPF, CNPJ, telefone, inscrição estadual, códigos importados e textos recebidos de integrações. Quando o conteúdo de substituição é omitido, a ocorrência encontrada é removida.

02 · SINTAXE

Sintaxe

StrTran( <cString>, <cSearch>, [cReplace], [nStart], [nCount] ) --> cResult

Parâmetros

cString

CaracterObrigatório

Texto original onde a busca será realizada.

cSearch

CaracterObrigatório

Sequência de caracteres que será procurada dentro do texto original.

cReplace

CaracterOpcional

Texto que substituirá cada ocorrência localizada. Quando omitido, remove a sequência encontrada.

Padrão: ""

nStart

NuméricoOpcional

Posição inicial a partir da qual a substituição deve começar. Use quando apenas parte do texto deve ser tratada.

nCount

NuméricoOpcional

Quantidade máxima de ocorrências a substituir. Use para limitar o alcance da substituição.

03 · EXEMPLO PRÁTICO

Remover pontuação de CPF/CNPJ

User Function ExStrTranDoc()
    Local cDocumento := "12.345.678/0001-90"

    cDocumento := StrTran(cDocumento, ".", "")
    cDocumento := StrTran(cDocumento, "/", "")
    cDocumento := StrTran(cDocumento, "-", "")

    MsgInfo("Documento limpo: " + cDocumento)
Return

Resultado esperado

Remove ponto, barra e hífen, retornando o documento somente com números: 12345678000190.

04 · EXEMPLO PRÁTICO

Trocar separador em texto importado

User Function ExStrTranSep()
    Local cLinha := "CODIGO;CLIENTE;VALOR"

    cLinha := StrTran(cLinha, ";", ",")

    MsgInfo("Linha ajustada: " + cLinha)
Return

Resultado esperado

Substitui ponto e vírgula por vírgula, gerando CODIGO,CLIENTE,VALOR.

05 · EXEMPLO PRÁTICO

Normalizar telefone antes de gravar

User Function ExStrTranFone()
    Local cTelefone := "(11) 99999-1234"

    cTelefone := StrTran(cTelefone, "(", "")
    cTelefone := StrTran(cTelefone, ")", "")
    cTelefone := StrTran(cTelefone, " ", "")
    cTelefone := StrTran(cTelefone, "-", "")

    MsgInfo("Telefone normalizado: " + cTelefone)
Return

Resultado esperado

Remove caracteres visuais e mantém o número em formato adequado para comparação, integração ou gravação padronizada.

BOAS PRÁTICAS

Use StrTran() quando a intenção for substituir ou remover uma sequência conhecida em uma string.
Para higienizar documentos e telefones, encadeie chamadas removendo pontos, barras, hífens e espaços.
Padronize o texto antes de comparar dados vindos de campos Character, que no Protheus costumam vir preenchidos com espaços à direita.
Quando precisar substituir apenas parte do texto, avalie o uso dos parâmetros de posição inicial e quantidade.

ARMADILHAS COMUNS

StrTran() trabalha com sequências literais; não é uma função de expressão regular.
A comparação é sensível ao conteúdo informado. Se houver variação de maiúsculas/minúsculas, normalize com Upper() ou Lower() antes.
Ao remover pontuação, cuidado para não alterar textos onde o caractere tenha significado real, como descrições livres ou observações.
Campos do banco podem conter espaços de preenchimento; combine com AllTrim() quando o objetivo for comparar ou exibir dados limpos.

Conteúdos relacionados

REFERÊNCIAS

Situação: Publicado
Página criada em: 03/09/2026 às 08:56
Última revisão em: 03/09/2026 às 08:56
Idioma original: Português
Revisão: Usina.BR