FUNCTIONPublished

StrTran

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

Replaces occurrences of a character sequence inside a string.

StringCharacterReplacementData cleanupEssential functions

01 · OVERVIEW

Overview

StrTran() locates a character sequence inside another string and replaces it with new content. In daily AdvPL work, it is very common for data normalization: removing punctuation from tax IDs, phone numbers, imported codes and texts received from integrations. When the replacement content is omitted, the matched occurrence is removed.

02 · SYNTAX

Syntax

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

Parameters

cString

CaracterRequired

Original text where the search will be performed.

cSearch

CaracterRequired

Character sequence to search for inside the original text.

cReplace

CaracterOptional

Text that replaces each located occurrence. When omitted, the sequence is removed.

Default: ""

nStart

NuméricoOptional

Initial position from which replacement should start. Use it when only part of the text should be processed.

nCount

NuméricoOptional

Maximum number of occurrences to replace. Use it to limit the replacement scope.

03 · PRACTICAL EXAMPLE

Remove tax ID punctuation

User Function ExStrTranTaxId()
    Local cTaxId := "12.345.678/0001-90"

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

    MsgInfo("Clean tax ID: " + cTaxId)
Return

Expected result

Removes dot, slash and hyphen, returning the identifier with digits only: 12345678000190.

04 · PRACTICAL EXAMPLE

Change separator in imported text

User Function ExStrTranSep()
    Local cLine := "CODE;CUSTOMER;AMOUNT"

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

    MsgInfo("Adjusted line: " + cLine)
Return

Expected result

Replaces semicolons with commas, producing CODE,CUSTOMER,AMOUNT.

05 · PRACTICAL EXAMPLE

Normalize phone number before saving

User Function ExStrTranPhone()
    Local cPhone := "(11) 99999-1234"

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

    MsgInfo("Normalized phone: " + cPhone)
Return

Expected result

Removes visual characters and keeps the number in a suitable format for comparison, integration or standardized storage.

BEST PRACTICES

Use StrTran() when the goal is to replace or remove a known sequence inside a string.
To sanitize tax IDs and phone numbers, chain calls that remove dots, slashes, hyphens and spaces.
Normalize text before comparing data coming from Character fields, which are often padded with trailing spaces in Protheus.
When only part of a text should be replaced, evaluate the start position and count parameters.

COMMON PITFALLS

StrTran() works with literal sequences; it is not a regular expression function.
Matching depends on the exact content provided. If letter case may vary, normalize with Upper() or Lower() first.
When removing punctuation, be careful not to change free-text descriptions where the character has real meaning.
Database fields may contain padding spaces; combine with AllTrim() when comparing or displaying clean values.

StrTran

Overview

Syntax

Parameters

Remove tax ID punctuation

Change separator in imported text

Normalize phone number before saving

Related content

Comments