Home /  Mappings /

# Numeric functions

Signature: `\$number(arg)`

Parameters:

• `arg` - An argument to be cast to number.

Casts the `arg` parameter to a number using the following casting rules

• Numbers are unchanged
• Strings that contain a sequence of characters that represent a legal JSON number are converted to that number
• Boolean `true` casts to `1`, Boolean `false` casts to `0`

If `arg` is not specified (i.e. this function is invoked with no arguments), then the context value is used as the value of `arg`.

Examples

ExpressionResult
\$number("5")5
["1", "2", "3", "4", "5"].\$number()[1, 2, 3, 4, 5]

## \$abs

Signature: `\$abs(number)`

Parameters:

• `number` - A number to get an absolute value of.

Returns the absolute value of the `number` parameter, i.e. if the number is negative, it returns the positive value.

If `number` is not specified (i.e. this function is invoked with no arguments), then the context value is used as the value of `number`.

Examples

ExpressionResult
\$abs(5)5
\$abs(-5)5

## \$floor

Signature: `\$floor(number)`

Parameters:

• `number` - The source number.

Returns the value of `number` rounded down to the nearest integer that is smaller or equal to `number`.

If `number` is not specified (i.e. this function is invoked with no arguments), then the context value is used as the value of `number`.

Examples

ExpressionResult
\$floor(5)5
\$floor(5.3)5
\$floor(5.8)5
\$floor(-5.3)-6

## \$ceil

Signature: `\$ceil(number)`

Parameters:

• `number` - The source number.

Returns the value of `number` rounded up to the nearest integer that is greater than or equal to `number`.

If `number` is not specified (i.e. this function is invoked with no arguments), then the context value is used as the value of `number`.

Examples

ExpressionResult
\$ceil(5)5
\$ceil(5.3)6
\$ceil(5.8)6
\$ceil(-5.3)-5

## \$round

Signature: `\$round(number [, precision])`

Parameters:

• `number` - The source number.
• `precision` - The `precision` parameter (which must be an integer) species the number of decimal places to be present in the rounded number.

If `precision` is not specified then it defaults to the value `0` and the number is rounded to the nearest integer. If `precision` is negative, then its value specifies which column to round to on the left side of the decimal place

Returns the value of the `number` parameter rounded to the number of decimal places specified by the optional `precision` parameter.

The `precision` parameter (which must be an integer) species the number of decimal places to be present in the rounded number. If `precision` is not specified then it defaults to the value `0` and the number is rounded to the nearest integer. If `precision` is negative, then its value specifies which column to round to on the left side of the decimal place

This function uses the Round half to even strategy to decide which way to round numbers that fall exactly between two candidates at the specified precision. This strategy is commonly used in financial calculations and is the default rounding mode in IEEE 754.

Examples

ExpressionResult
\$round(123.456)123
\$round(123.456, 2)123.46
\$round(123.456, -1)120
\$round(123.456, -2)100
\$round(11.5)12
\$round(12.5)12
\$round(125, -1)120

## \$power

Signature: `\$power(base, exponent)`

Parameters:

• `base` - The base number (`base.css-16ei94f{color:var(--gray10);font-size:0.875em;vertical-align:baseline;margin-bottom:16px;display:block;}p .css-16ei94f,li .css-16ei94f,.css-16ei94f .css-16ei94f{color:inherit;vertical-align:top;margin-bottom:0;display:inline;}exponent`).
• `exponent` - The exponent number (`baseexponent`).

Returns the value of `base` raised to the power of `exponent` (`baseexponent`).

If `base` is not specified (i.e. this function is invoked with one argument), then the context value is used as the value of `base`.

An error is thrown if the values of `base` and `exponent` lead to a value that cannot be represented as a JSON number (e.g. Infinity, complex numbers).

Examples

ExpressionResult
\$power(2, 8)256
\$power(2, 0.5)1.414213562373
\$power(2, -2)0.25

## \$sqrt

Signature: `\$sqrt(number)`

Parameters:

• `number` - The source number.

Returns the square root of the value of the `number` parameter.

If `number` is not specified (i.e. this function is invoked with one argument), then the context value is used as the value of `number`.

Examples

ExpressionResult
\$sqrt(4)2
\$sqrt(2)1.414213562373

## \$random

Signature: `\$random()`

Returns a pseudo random number greater than or equal to zero and less than one `(0 ≤ n < 1)`

Examples

ExpressionResult
\$random()0.7973541067127
\$random()0.414213562373
\$random()0.6558078550072

## \$formatNumber

Signature: `\$formatNumber(number, picture [, options])`

Parameters:

• `number` - The source number.
• `picture` - Format of the desired decimal representation.

The picture string parameter defines how the number is formatted and has the same syntax as fn:format-number.

• `options` - The optional third argument `options` is used to override the default locale specific formatting characters such as the decimal separator.

If supplied, this argument must be an object containing name/value pairs specified in the decimal format section of the XPath F\&O 3.1 specification.

Casts the `number` to a string and formats it to a decimal representation as specified by the `picture` string.

The behaviour of this function is consistent with the XPath/XQuery function fn:format-number as defined in the XPath F\&O 3.1 specification. The picture string parameter defines how the number is formatted and has the same syntax as fn:format-number.

The optional third argument `options` is used to override the default locale specific formatting characters such as the decimal separator. If supplied, this argument must be an object containing name/value pairs specified in the decimal format section of the XPath F\&O 3.1 specification.

Examples

ExpressionResult
\$formatNumber(12345.6, '#,###.00')"12,345.60"
\$formatNumber(1234.5678, "00.000e0")"12.346e2"
\$formatNumber(34.555, "#0.00;(#0.00)")"34.56"
\$formatNumber(-34.555, "#0.00;(#0.00)")"(34.56)"

## \$formatBase

Signature: `\$formatBase(number [, radix])`

Parameters:

• `number` - The source number.
• `radix` - The optional `radix` parameter represents the mathematical base of the `number`.

If `radix` is not specified, then it defaults to base 10. `radix` can be between 2 and 36, otherwise an error is thrown.

Casts the `number` to a string and formats it to an integer represented in the number base specified by the `radix` argument. If `radix` is not specified, then it defaults to base 10. `radix` can be between 2 and 36, otherwise an error is thrown.

Examples

ExpressionResult
\$formatBase(100, 2)"1100100"
\$formatBase(2555, 16)"9fb"

## \$formatInteger

Signature: `\$formatInteger(number, picture)`

Parameters:

• `number` - The source number.
• `picture` - Format of the desired integer representation.

The picture string parameter defines how the number is formatted and has the same syntax as fn:format-integer.

Casts the `number` to a string and formats it to an integer representation as specified by the `picture` string.

The behaviour of this function is consistent with the two-argument version of the XPath/XQuery function fn:format-integer as defined in the XPath F\&O 3.1 specification. The picture string parameter defines how the number is formatted and has the same syntax as fn:format-integer.

Examples

ExpressionResult
\$formatInteger(2789, 'w')"two thousand, seven hundred and eighty-nine"
\$formatInteger(1999, 'I')"MCMXCIX"

## \$parseInteger

Signature: `\$parseInteger(string, picture)`

Parameters:

• `string` - The source string to parse.
• `picture` - Format of the integer representation.

The picture string parameter has the same format as `\$formatInteger`, which has the same syntax as fn:format-integer.

Parses the contents of the `string` parameter to an integer (as a JSON number) using the format specified by the `picture` string. The picture string parameter has the same format as `\$formatInteger`. Although the XPath specification does not have an equivalent function for parsing integers, this capability has been added to JSONata.

Examples

ExpressionResult
\$parseInteger("twelve thousand, four hundred and seventy-six", 'w')12476
\$parseInteger('12,345,678', '#,##0')12345678
\$number\$abs\$floor\$ceil\$round\$power\$sqrt\$random\$formatNumber\$formatBase\$formatInteger\$parseInteger