## `$number()`

**用法:** `$number(arg)`

使用以下轉換規則將 arg 參數轉換為數字

* 數字不變
* 包含表示合法 JSON 數字的字符序列的字符串將轉換為該數字
* 十六進制數以 `0x` 開頭，八進制數以 `0o` 開頭，二進制數以 `0o` 開頭
* 布爾 `true` 轉換為 `1`，布爾 `false` 轉換為 `0`
* 所有其他值都會引發錯誤。

如果未指定 `arg`（即此函數在沒有參數的情況下被調用），則上下文值將用作 `arg` 的值。

舉例：

* `$number("5")` => `5`
* `$number("0x12")` => `0x18`
* `["1", "2", "3", "4", "5"].$number()` => `[1, 2, 3, 4, 5]`

## `$abs()`

**用法:** `$abs(number)`

返回數字參數的絕對值，即如果 `number` 為負，則返回正值。

如果未指定 `number`（即此函數在沒有參數的情況下調用），則使用上下文值作為 `number` 的值。

舉例：

* `$abs(5)` => `5`
* `$abs(-5)` => `5`

## `$floor()`

**用法:** `$floor(number)`

返回四舍五入到小于或等于 `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`（即此函數在沒有參數的情況下調用），則使用上下文值作為 `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` 為負，則其值指定小數點左側四舍五入到那一列。

此函數使用舍入半偶數策略來決定以指定的精度對恰好位于兩個候選之間的數字進行舍入。此策略通常用于財務計算，是 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`（即使用一個參數調用此函數），則使用上下文值作為 base 的值。

如果 `base` 和指數的值導致無法表示為 JSON 數字的值（例如無窮大、復數），則會拋出錯誤。

舉例：

* `$power(2, 8)` => `256`
* `$power(2, 0.5)` => `1.414213562373`
* `$power(2, -2)` => `0.25`

## `$sqrt()`

**用法:** `$sqrt(number)`

返回 `number` 參數值的平方根。

如果未指定 `number`（即使用一個參數調用此函數），則使用上下文值作為 `number` 的值。

如果 `number` 的值為負，則拋出錯誤。

舉例：

* `$sqrt(4)` => `2`
* `$sqrt(2)` => `1.414213562373`

## `$random()`

**用法:** `$random()`

返回一個大于等于零且小于 1 的偽隨機數（`0 ≤ n < 1`）

舉例：

* `$random()` => `0.7973541067127`
* `$random()` => `0.4029142127028`
* `$random()` => `0.6558078550072`

## `$formatNumber()`

**用法:** `$formatNumber(number, picture [, options])`

將 `number` 轉換為字符串，并將其格式化為 `picture` 字符串指定的十進制表示形式。

此函數的行為與 XPath F&O 3.1 規范中定義的 XPath/XQuery 函數 fn:format number 一致。圖片字符串參數定義了數字的格式，其語法與 fn:format number 相同。

可選的第三個參數 `options` 用于覆蓋默認的特定于區域設置的格式化字符，如小數分隔符。如果提供，此參數必須是一個包含 XPath F&O 3.1 規范的十進制格式部分中指定的名稱/值對的對象。

舉例：

* `$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` 表示的整數。如果未指定 `radix`，則默認為基數 10。基數可以在 2 和 36 之間，否則會拋出錯誤。

舉例：

* `$formatBase(100, 2)` => `"1100100"`
* `$formatBase(2555, 16)` => `"9fb"`

## `$formatInteger()`

**用法:** `$formatInteger(number, picture)`

將 `number` 轉換為字符串，并將其格式化為 `picture` 字符串指定的整數表示形式。

此函數的行為與 XPath F&O 3.1 規范中定義的 XPath/XQuery 函數 fn:format integer 的雙參數版本一致。圖片字符串參數定義了數字的格式，其語法與 fn:format integer 相同。

舉例：

* `$formatInteger(2789, 'w')` => `"two thousand, seven hundred and eighty-nine"`
* `$formatInteger(1999, 'I')` => `"MCMXCIX"`

## `$parseInteger()`

**用法:** `$parseInteger(string, picture)`

使用 `picture` 字符串指定的格式將字符串參數的內容解析為整數（JSON 數字）。圖片 `string` 參數的格式與 `$formatInteger` 相同。雖然 XPath 規范沒有解析整數的等效功能，但 JSONata 中添加了此功能。

舉例：

* `$parseInteger("twelve thousand, four hundred and seventy-six", 'w')` => `12476`
* `$parseInteger('12,345,678', '#,##0')` => `12345678`

17、數值函數