Funções numéricas

Aprenda sobre as funções numéricas da Digibee Integration Platform e como utilizá-las.

As funções foram criadas para:

Acelerar ainda mais a criação das suas integrações.
Diminuir a complexidade dos seus pipelines.
Simplificar conversões e transformações dos dados durante o fluxo dos seus pipelines.

As funções numéricas realizam tratamentos de números e estão disponíveis para componentes que suportam expressões com Double Braces. Para saber como passar informações para os componentes utilizando esse recurso, leia a documentação Funções Double Braces.

FORMATNUMBER

A função FORMATNUMBER é usada para formatar números em um formato de texto.

Sintaxe

FORMATNUMBER(value, "pattern", "locale":opcional, "rounding":opcional)

valor: o número a ser formatado (pode ser um número ou uma string).
padrão: o padrão a ser usado. Ele inclui um subpadrão positivo e um negativo, como "#,##0.00;(#,##0.00)". Cada subpadrão consiste em um prefixo, uma parte numérica e um sufixo. A presença do subpadrão negativo é opcional; se não for especificado, o subpadrão positivo precedido pelo sinal de menos localizado (‘-’ na maioria dos locais) serve como subpadrão negativo. Portanto, “0.00” sozinho é equivalente a “0.00;-0.00”.
locale: a especificação do locale deve ser levada em consideração ao gerar números. Se o locale não estiver definido, en-us será levado em consideração.
arredondamento: o tipo de arredondamento a ser usado. UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN. O padrão é HALF_EVEN.

Padrão

Abaixo você encontrará os padrões de caracteres especiais aceitos pela função, que foram retirados da documentação do Java e livremente traduzidos para o português.

Símbolo	Localização	Localizado?	Significado
0	Número	Sim	Dígito
#	Número	Sim	Dígito, zero aparece como ausente
.	Número	Sim	Separador decimal ou separador decimal monetário
-	Número	Sim	Sinal de menos
,	Número	Sim	Separador de agrupamento
E	Número	Sim	Separador entre mantissa e expoente na notação científica
;	Limite de subpadrão	Sim	Separador de subpadrões positivos e negativos
%	Prefixo ou sufixo	Sim	Multiplicar por 100 e exibir como porcentagem

Símbolo

Localização

Localizado?

Significado

Número

Sim

Dígito

Número

Sim

Dígito, zero aparece como ausente

Número

Sim

Separador decimal ou separador decimal monetário

Número

Sim

Sinal de menos

Número

Sim

Separador de agrupamento

Número

Sim

Separador entre mantissa e expoente na notação científica

;

Limite de subpadrão

Sim

Separador de subpadrões positivos e negativos

Prefixo ou sufixo

Sim

Multiplicar por 100 e exibir como porcentagem

Alguns outros exemplos de padrão:

Padrão	Número	String formatada
###.###	123.456	123.456
###.#	123.456	123.5
###,###.##	123456.789	123,456.79000
###	9.95	009.95
##0.###	0.95	0.95

Função em uso

Exemplo 1:

Vamos assumir que nós temos o número:

{
    "num": 3.8454
}

E executemos o seguinte teste:

{
  "test_UP": {{ FORMATNUMBER(message.num,"#.###", null, "UP") }},
  "test_DOWN": {{ FORMATNUMBER(message.num,"#.###", null, "DOWN") }},
  "test_CEILING": {{ FORMATNUMBER(message.num,"#.###", null, "CEILING") }},
  "test_FLOOR": {{ FORMATNUMBER(message.num,"#.###", null, "FLOOR") }},
  "test_HALF_UP": {{ FORMATNUMBER(message.num,"#.###", null, "HALF_UP") }},
  "test_HALF_DOWN": {{ FORMATNUMBER(message.num,"#.###", null, "HALF_DOWN") }},
  "test_HALF_EVEN": {{ FORMATNUMBER(message.num,"#.###", null, "HALF_EVEN") }}
}

Esse será o resultado:

{
  "test_UP": "3.846",
  "test_DOWN": "3.845",
  "test_CEILING": "3.846",
  "test_FLOOR": "3.845",
  "test_HALF_UP": "3.845",
  "test_HALF_DOWN": "3.845",
  "test_HALF_EVEN": "3.845"
}

Exemplo 2:

Agora vamos supor que temos esses dois números:

{
  "number": 123456.9123,
  "negative": -987.123
}

E apliquemos as seguintes conversões:

{
  "number-US":{{ FORMATNUMBER(message.number, "###,###.###", "us-EN") }},
  "number-BR":{{ FORMATNUMBER(message.number, "###,###.###", "pt-BR") }},
  "number-BR-1":{{ FORMATNUMBER(message.number, "###,###.#", "pt-BR") }},
  "number-positive-BR-a": {{ FORMATNUMBER(message.number, "'+'###,###.###;'-'###,###.###", "pt-BR") }},
  "number-negative-BR": {{ FORMATNUMBER(message.negative, "###,###.###'C';###,###.###'D'", "pt-BR") }},
  "number-negative-BR-a": {{ FORMATNUMBER(message.negative, "'+'###,###.###;'-'###,###.###", "pt-BR") }}
}

Esse será o resultado:

{
  "number-US": "123,456.912",
  "number-BR": "123.456,912",
  "number-BR-1": "123.456,9",
  "number-positive-BR-a": "+123.456,912",
  "number-negative-BR": "987,123D",
  "number-negative-BR-a": "-987,123"
}

TODOUBLE

Utilizando Double Braces, você pode combinar a função com o acesso ao elemento do JSON de entrada de um componente.

A função TODOUBLE é aplicada para retornar o valor double de um número inteiro.

Sintaxe

TODOUBLE(num1)

Exemplo:

{
    "a": 12
}
{
    "doub": {{ TODOUBLE( message.a ) }}
}

O retorno dessa função será 12.0.

TOINT

Utilizando Double Braces, você pode combinar a função com o acesso ao elemento do JSON de entrada de um componente.

A função TOINT é aplicada para retornar o valor inteiro de um número double.

Sintaxe

TOINT(num1)

Exemplo:

{
    "a": 12.345
}
{
    "int": {{ TOINT( message.a ) }}
}

O retorno dessa função será 12.

TOLONG

Utilizando Double Braces, você pode ter retornado de um número um valor no tipo LONG. É possível receber tanto uma string como um número como parâmetro de entrada.

Sintaxe

TOLONG(num1)

Exemplo:

{
    "a": 12.345
}
{
    "long": {{ TOLONG( message.a ) }}
}

O retorno dessa função será 12.

TONUMBER

A função TONUMBER permite que você converta uma string para um valor numérico com base no seu formato de origem e locale.

Sintaxe

TONUMBER(string, formatSource, localeSource?, asInteger?)

Os parâmetros indicados com "?" são opcionais.

string: string a ser convertida
formatSource: formato de origem da string. Ex.: "###.###", "###.#", "###,###.##"
localeSource: locale da string, que se não for definido, será considerado "en-us"
asInteger: valor booleano que indica se a string deve ser convertida para um número inteiro. Caso não seja definido, o valor padrão será false.

Digamos que você precise converter duas strings referentes a um valor numérico genérico e um valor monetário:

{
    "generic": "150.33",
    "currency": "R$ 300.754,15"
}

Aplicando a conversão:

{
    "generic": {{ TONUMBER(message.generic, "###.##") }},
    "currency": {{ TONUMBER(message.currency, "'R$ '###,###.##", "pt-br") }}
}

O resultado será:

{
    "generic": 150.33,
    "currency": 300754.15
}

Outros exemplos de formatação:

String	Formato	Numérico
"123.456"	###.#	123.5
"009.95"	000.###	9.95
"0.95"	##0.###	0.95
"-300"	'-'###	-300

String

Formato

Numérico

"123.456"

###.#

123.5

"009.95"

000.###

9.95

"0.95"

##0.###

0.95

"-300"

'-'###

-300

RANDOMNUMBERS

A função RANDOMNUMBERS permite que você gere números inteiros randômicos com base em um intervalo de valores.

Sintaxe

RANDOMNUMBERS(minValue, maxValue)

Digamos que você precise gerar um número randômico dentro do intervalo de 0 a 50000.

Gerando o número:

{
    "randomNumber": {{ RANDOMNUMBERS(0, 50000) }}
}

O resultado será:

{
    "randomNumber": 37122
}

Os valores que definem o intervalo numérico são inclusivos.

A função tem limitação numérica e aceita apenas valores dentro do intervalo de -9223372036854775808 a 9223372036854775807. Qualquer valor fora desses limites acarretará em uma execução imprevisível da função.

Outras funções

Conheça também:

AnteriorFunções de utilidades PróximoFunções de string

Atualizado há 7 meses