FUNCIóNPublicado

StrTran

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

Reemplaza ocurrencias de una secuencia de caracteres dentro de una cadena.

StringCaracterSustituciónLimpieza de datosFunciones esenciales

01 · DESCRIPCIÓN GENERAL

Descripción general

StrTran() localiza una secuencia de caracteres dentro de otra cadena y la reemplaza por un nuevo contenido. En el trabajo diario con AdvPL, se usa mucho para normalizar datos: quitar puntuación de documentos fiscales, teléfonos, códigos importados y textos recibidos de integraciones. Cuando se omite el contenido de reemplazo, la ocurrencia encontrada se elimina.

02 · SINTAXIS

Sintaxis

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

Parámetros

cString

CaracterObligatorio

Texto original donde se realizará la búsqueda.

cSearch

CaracterObligatorio

Secuencia de caracteres que se buscará dentro del texto original.

cReplace

CaracterOpcional

Texto que reemplaza cada ocurrencia encontrada. Si se omite, la secuencia se elimina.

Predeterminado: ""

nStart

NuméricoOpcional

Posición inicial desde la cual debe comenzar el reemplazo. Úsala cuando solo una parte del texto deba tratarse.

nCount

NuméricoOpcional

Cantidad máxima de ocurrencias que se reemplazarán. Úsala para limitar el alcance del reemplazo.

03 · EJEMPLO PRÁCTICO

Quitar puntuación de documento fiscal

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

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

    MsgInfo("Documento limpio: " + cDocumento)
Return

Resultado esperado

Quita punto, barra y guion, devolviendo el documento solo con números: 12345678000190.

04 · EJEMPLO PRÁCTICO

Cambiar separador en texto importado

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

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

    MsgInfo("Línea ajustada: " + cLinea)
Return

Resultado esperado

Reemplaza punto y coma por coma, generando CODIGO,CLIENTE,VALOR.

05 · EJEMPLO PRÁCTICO

Normalizar teléfono antes de guardar

User Function ExStrTranTelefono()
    Local cTelefono := "(11) 99999-1234"

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

    MsgInfo("Teléfono normalizado: " + cTelefono)
Return

Resultado esperado

Quita caracteres visuales y mantiene el número en un formato adecuado para comparación, integración o grabación estandarizada.

BUENAS PRÁCTICAS

Usa StrTran() cuando la intención sea reemplazar o eliminar una secuencia conocida dentro de una cadena.
Para limpiar documentos y teléfonos, encadena llamadas que eliminen puntos, barras, guiones y espacios.
Normaliza el texto antes de comparar datos provenientes de campos Character, que en Protheus suelen venir rellenados con espacios a la derecha.
Cuando solo parte del texto deba reemplazarse, evalúa los parámetros de posición inicial y cantidad.

ERRORES COMUNES

StrTran() trabaja con secuencias literales; no es una función de expresión regular.
La comparación depende del contenido exacto informado. Si puede variar entre mayúsculas y minúsculas, normaliza con Upper() o Lower() antes.
Al quitar puntuación, cuidado con textos libres donde el carácter tenga significado real.
Los campos de base de datos pueden contener espacios de relleno; combina con AllTrim() cuando el objetivo sea comparar o mostrar datos limpios.

Contenido relacionado

REFERENCIAS

Estado: Publicado
Página creada el: 03/09/2026 a las 08:56
Última revisión el: 03/09/2026 a las 08:56
Idioma original: Portugués
Revisión: Usina.BR