Transform

Aplica mascara de formatacao a valor numerico ou string. Padrao pra exibir moeda (R$ 1.234,56), CPF/CNPJ, CEP, telefone.

Assinatura: Transform(xValor, cMascara) -> cString

Retorna: Character

Transform aplica mascara de formatacao em valor numerico ou string. E o jeito padrao de transformar 1234.56 em "R$ 1.234,56" ou "12345678901" em "123.456.789-01".

Sintaxe

Transform(xValor, cMascara) --> cString

Mascaras numericas

Mascara	Valor	Resultado
`"@E 999,999.99"`	1234.56	" 1.234,56" (Europeu - BR)
`"@E 999,999,999.99"`	1234567.89	"1.234.567,89"
`"R$ @E 999,999.99"`	1234.56	"R$ 1.234,56"
`"99.9 %"`	15.5	"15.5 %"
`"@R 9999999"`	42	"0000042"

Mascaras de string

Mascara	Valor	Resultado
`"@R 999.999.999-99"`	"12345678901"	"123.456.789-01"
`"@R 99.999.999/9999-99"`	"12345678000195"	"12.345.678/0001-95"
`"@R 99999-999"`	"01001000"	"01001-000"
`"@R (99) 9999-9999"`	"1133334444"	"(11) 3333-4444"
`"@R (99) 99999-9999"`	"11999998888"	"(11) 99999-8888"

Exemplos completos

// Moeda brasileira
Transform(1234567.89, "@E 999,999,999.99")
// "1.234.567,89"

// CPF
Transform("12345678901", "@R 999.999.999-99")
// "123.456.789-01"

// CNPJ
Transform("12345678000195", "@R 99.999.999/9999-99")
// "12.345.678/0001-95"

// CEP
Transform("01001000", "@R 99999-999")
// "01001-000"

// Telefone movel
Transform("11999998888", "@R (99) 99999-9999")
// "(11) 99999-8888"

Caso pratico: imprimir titulo financeiro

// Linha de relatorio com valor formatado
cLinha := ""
cLinha += PadR(AllTrim(SA1->A1_NOME), 40)
cLinha += " | "
cLinha += DToC(SE1->E1_VENCREAL)
cLinha += " | "
cLinha += PadL(Transform(SE1->E1_VALOR, "@E 999,999,999.99"), 18)
// "EMPRESA TESTE LTDA                     | 30/05/2026 |       12.500,00"

Tokens de mascara explicados

Token	Significado
`9`	Digito numerico
`A`	Letra
`X`	Qualquer caractere
`.` ou `,`	Separador (decimal/milhar conforme @E)
`@E`	Modo europeu (BR): . = milhar, , = decimal
`@R`	Mascara de saida (overlay) — caracteres extras ficam na string
`@Z`	Mostra zeros como branco

Pegadinhas

Sem @E em base BR, "999,999.99" usa padrao americano (virgula milhar, ponto decimal) — output errado pra Brasil.
Mascara com mais digitos que valor = zeros/espacos a esquerda.
Mascara com menos digitos que valor = trunca esquerda (perde precisao!).
Performance — Transform em loop apertado tem custo. Em relatorios gigantes, considere format direto via SUM SQL.
Negativos aparecem como "-1.234,56" por default. Pra contabil tradicional (entre parenteses), use mascara "@E (999,999.99)" (com cuidado, comportamento varia).

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`xValor`	Any	sim	Valor numerico ou string.
`cMascara`	Character	sim	Mascara com tokens.