Numerical functions

Learn about numerical functions in the Digibee Integration Platform and how to use them.

The numerical functions treat numbers and are available for components that support Double Braces expressions. To know how to provide information to the components using this resource, refer to Double Braces Functions.

FORMATNUMBER

The FORMATNUMBER function is used to format numbers in a text format.

Syntax

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

• value: the number to be formatted (can be a number or string).

• pattern: the pattern to be used. It includes both a positive and a negative subpattern, such as "#,##0.00;(#,##0.00)". Each subpattern consists of a prefix, a numeric part, and a suffix. The presence of the negative subpattern is optional; if it is not specified, the positive subpattern preceded by the localized minus sign ('-' in most locales) serves as the negative subpattern. Therefore, "0.00" alone is equivalent to "0.00;-0.00".

• locale: the specification of the locale must be taken into account when generating numbers. If the locale isn't defined, en-us is taken into account.

• rounding: the rounding type to be used: UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN. The default is HALF_EVEN

Pattern

Below you will find the special character patterns accepted by the function, which are taken from the Java documentation.

Symbol	Location	Localized?	Meaning
0	Number	Yes	Digit
#	Number	Yes	Digit, zero shows as absent
.	Number	Yes	Decimal separator or monetary decimal separator
-	Number	Yes	Minus sign
,	Number	Yes	Grouping separator
E	Number	Yes	Separates mantissa and exponent in scientific notation
;	Subpattern boundary	Yes	Separates positive and negative subpatterns
%	Prefix or suffix	Yes	Multiply by 100 and show as percentage

Some other pattern examples:

Pattern	Number	Formatted string
###.###	123.456	123.456
###.#	123.456	123.5
###,###.##	123456.789	123,456.79000
###	9.95	009.95
##0.###	0.95	0.95

Function in use

Example 1:

Let's assume we have the number:

{
    "num": 3.8454
}

And execute the following test:

{
  "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") }}
}

This will be the result:

{
  "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"
}

Example 2:

Now let’s suppose we have these two numbers:

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

And apply the following conversions:

{
  "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") }}
}

This will be the result:

{
  "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

By using Double Braces, you can combine the function with the access to the input JSON element of a component.

The TODOUBLE function is applied to return the double value of a whole number.

Syntax

TODOUBLE(num1)

Example:

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

The return of this function will be 12.0.

TOINT

By using Double Braces, you can combine the function with the access to the input JSON element of a component.

The TOINT function is applied to return the whole number of a double number.

Syntax

TOINT(num1)

Example:

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

The return of this function will be 12.

TOLONG

By using Double Braces, you can have a LONG-type value returned from a number. It's possible to receive not only a string, but also a number as an input parameter.

Syntax

TOLONG(num1)

Example:

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

The return of this function will be 12.

TONUMBER

The TONUMBER function allows you to convert a string value to a numeric value based on its source format and locale.

Syntax

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

The parameters indicated with "?" are optionals.

• string: the string to be converted

• formatSource: source format of the string. Eg.: "###.###", "###.#", "###,###.##"

• localeSource: the string locale, which if not informed, will be considered "en-us"

• asInteger: boolean value that indicates if the string must be converted to an integer numeric value. In case it is not defined, the default value is false.

Let's say you need to convert two strings referring to a generic numeric value and a monetary value:

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

Applying the conversion:

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

The result will be:

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

Other formatting examples:

String	Format	Numerical
"123.456"	###.#	123.5
"009.95"	000.###	9.95
"0.95"	##0.###	0.95
"-300"	'-'###	-300

RANDOMNUMBERS

The RANDOMNUMBERS function allows you to generate random integer numbers based on a range of values.

Syntax

RANDOMNUMBERS(minValue, maxValue)

Let's say you need to generate a random number between 0 and 50000.

Generate the number:

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

The result will be:

{
    "randomNumber": 37122
}

The values that define the range are inclusive.

The function has a numerical limitation and only accepts values between the range of -9223372036854775808 to 9223372036854775807. Any other value out of those limits will result in an unpredictable execution of the function.