# Funções numéricas 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*](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/double-braces-functions). ## FORMATNUMBER A função FORMATNUMBER é usada para formatar números em um formato de texto. ### Sintaxe ```json 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](https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html) 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: ```json { "num": 3.8454 } ``` E executemos o seguinte teste: ```json { "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: ```json { "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: ```json { "number": 123456.9123, "negative": -987.123 } ``` E apliquemos as seguintes conversões: ```json { "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: ```json { "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 ```json TODOUBLE(num1) ``` Exemplo: ```json { "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 ```json TOINT(num1) ``` Exemplo: ```json { "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 ```json TOLONG(num1) ``` Exemplo: ```json { "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 ```json 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: ```json { "generic": "150.33", "currency": "R$ 300.754,15" } ``` Aplicando a conversão: ```json { "generic": {{ TONUMBER(message.generic, "###.##") }}, "currency": {{ TONUMBER(message.currency, "'R$ '###,###.##", "pt-br") }} } ``` O resultado será: ```json { "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 ```json RANDOMNUMBERS(minValue, maxValue) ``` Digamos que você precise gerar um número randômico dentro do intervalo de 0 a 50000. Gerando o número: ```json { "randomNumber": {{ RANDOMNUMBERS(0, 50000) }} } ``` O resultado será: ```json { "randomNumber": 37122 } ``` Os valores que definem o intervalo numérico são inclusivos. {% hint style="info" %} 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. {% endhint %}