Funções numéricas

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

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

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

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.