Числовые функции

$number()

Сигнатура: $number(arg)

Приводит arg к числу по правилам:

• числа не изменяются;
• строки с допустимой записью JSON-числа преобразуются в это число;
• шестнадцатеричные числа начинаются с 0x, восьмеричные — с 0o, двоичные — с 0b;
• true преобразуется в 1, false — в 0;
• для остальных значений возникает ошибка.

Если arg не указан, используется значение контекста.

Примеры:

• $number("5") => 5
• $number("0x12") => 18
• ["1", "2", "3", "4", "5"].$number() => [1, 2, 3, 4, 5]

$abs()

Сигнатура: $abs(number)

Возвращает абсолютное значение number: для отрицательного числа возвращается положительное. Если number не указан, используется значение контекста.

Примеры: $abs(5) => 5; $abs(-5) => 5.

$floor()

Сигнатура: $floor(number)

Возвращает number, округлённое вниз до ближайшего целого, меньшего или равного number. Если number не указан, используется значение контекста.

Примеры: $floor(5) => 5; $floor(5.3) => 5; $floor(5.8) => 5; $floor(-5.3) => -6.

$ceil()

Сигнатура: $ceil(number)

Возвращает number, округлённое вверх до ближайшего целого, большего или равного number. Если number не указан, используется значение контекста.

Примеры: $ceil(5) => 5; $ceil(5.3) => 6; $ceil(5.8) => 6; $ceil(-5.3) => -5.

$round()

Сигнатура: $round(number [, precision])

Возвращает number, округлённое до числа десятичных знаков, заданного необязательным precision. precision должен быть целым. По умолчанию это 0, то есть округление до целого. Отрицательное precision задаёт разряд слева от десятичной точки, до которого нужно округлять.

Для значений ровно посередине функция использует стратегию round half to even — обычный подход для финансовых расчётов и режим округления IEEE 754 по умолчанию.

Примеры:

• $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()

Сигнатура: $power(base, exponent)

Возвращает base в степени exponent (base^exponent). Если base не указан, используется значение контекста. Если результат нельзя представить JSON-числом (например, бесконечность или комплексное число), возникает ошибка.

Примеры: $power(2, 8) => 256; $power(2, 0.5) => 1.414213562373; $power(2, -2) => 0.25.

$sqrt()

Сигнатура: $sqrt(number)

Возвращает квадратный корень number. Если number не указан, используется значение контекста. Для отрицательного значения возникает ошибка.

Примеры: $sqrt(4) => 2; $sqrt(2) => 1.414213562373.

$random()

Сигнатура: $random()

Возвращает псевдослучайное число, большее или равное нулю и меньшее единицы (0 ≤ n < 1).

Примеры: $random() => 0.7973541067127; $random() => 0.4029142127028; $random() => 0.6558078550072.

$formatNumber()

Сигнатура: $formatNumber(number, picture [, options])

Преобразует number в строку и форматирует десятичное представление согласно строке picture.

Поведение согласовано с XPath/XQuery-функцией fn:format-number из спецификации XPath F&O 3.1. picture определяет формат и использует тот же синтаксис. Необязательный объект options переопределяет локалезависимые символы форматирования (например, десятичный разделитель) и должен содержать пары имя/значение из раздела decimal format.

Примеры:

• $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)"
• $formatNumber(0.14, "01%") => "14%"
• $formatNumber(0.14, "###pm", {"per-mille": "pm"}) => "140pm"
• $formatNumber(1234.5678, "①①.①①①e①", {"zero-digit": "\u245f"}) => "①②.③④⑥e②"

$formatBase()

Сигнатура: $formatBase(number [, radix])

Преобразует number в строку и представляет его целым числом в системе счисления, заданной radix. По умолчанию основание — 10. radix может быть от 2 до 36, иначе возникает ошибка.

Примеры: $formatBase(100, 2) => "1100100"; $formatBase(2555, 16) => "9fb".

$formatInteger()

Сигнатура: $formatInteger(number, picture)

Преобразует number в строку и форматирует его целое представление по picture. Поведение согласовано с двухаргументной XPath/XQuery-функцией fn:format-integer; строка picture имеет тот же синтаксис.

Примеры: $formatInteger(2789, 'w') => "two thousand, seven hundred and eighty-nine"; $formatInteger(1999, 'I') => "MCMXCIX".

$parseInteger()

Сигнатура: $parseInteger(string, picture)

Разбирает string в целое JSON-число, используя формат picture. Формат picture такой же, как у $formatInteger. Хотя в XPath нет эквивалентной функции разбора целых, эта возможность добавлена в JSONata.

Примеры: $parseInteger("twelve thousand, four hundred and seventy-six", 'w') => 12476; $parseInteger('12,345,678', '#,##0') => 12345678.