> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 數字格式化器

> 用於在 ArcScript 中對數值執行算術運算、數值比較、舍入和格式化的格式化器。

export const siteNameShort = "知行之橋";

## 常用數字格式化器

以下格式化器是最常用的數字格式化器。每個格式化器都提供了一個範例以供參考。

<Note>某些格式化器的可選參數周圍的方括號不是必需的。它們用於表示該參數是可選的。</Note>

### add(value)

將輸入屬性/值與 *value* 參數相加，並傳回結果。預設值為 `1`。

#### 範例

```xml theme={null}
<!-- count the number of loops in an XML document using xmlDOMSearch -->

<arc:set attr="xml.uri" value="[FilePath]" />
<arc:set attr="xml.xpath" value="/Items/test/loop" />

<arc:call op="xmlDOMSearch" in="xml">
  <!-- this code executes for each occurrence of the 'xpath' in the XML document -->
  <arc:set attr="loopCount" value="[loopCount | def(0) | add(1)]" />
</arc:call>
```

### greaterthan(value\[, ifgreater]\[, ifnotgreater])

如果輸入屬性/值大於 *value* 參數，則傳回 *true*；否則傳回 *false*。

如果提供了 *ifgreater*，當輸入大於 *value* 時會傳回該值而不是 *true*；如果提供了 *ifnotgreater*，當輸入不大於 *value* 時會傳回該值而不是 *false*。

#### 範例

```xml theme={null}
<arc:set attr="totalCost" value="[xpath(Items/Order/TotalCost)]" />
<arc:if exp="[totalCost | greaterthan(1000)]">
  <arc:set attr="highValueOrder" value="true" />
</arc:if>
```

### lessthan(value\[, ifless]\[, ifnotless])

如果輸入屬性/值小於 *value* 參數，則傳回 *true*；否則傳回 *false*。

如果提供了 *ifless*，當輸入小於 *value* 時會傳回該值而不是 *true*；如果提供了 *ifnotless*，當輸入不小於 *value* 時會傳回該值而不是 *false*。

#### 範例

```xml theme={null}
<arc:set attr="totalCost" value="[xpath(Items/Order/TotalCost)]" />
<arc:if exp="[totalCost | lessthan(0)]">
  <arc:throw code="1" desc="ERROR: Invalid order total." />
</arc:if>
```

### multiply(value)

將輸入屬性/值與 *value* 參數相乘，並傳回結果。

#### 範例

```xml theme={null}
<!-- find the total cost by multiplying the price and the quantity of a purchased item -->
<arc:set attr="item.price" value="[xpath(lineitem/costperunit)]" />
<arc:set attr="item.quantity" value="[xpath(lineitem/quantitypurchased)]" />
<arc:set attr="item.totalcost" value="[item.price | multiply([item.quantity])]" />
```

### rand(upperBound)

生成一個介於 0 和 *upperBound* 之間的隨機整數。

此格式化器不會修改輸入屬性（變數），因此不需要輸入屬性。

#### 範例

```xml theme={null}
<!-- add a random number to the end of a filename -->
<arc:set attr="myFilename" value="myfile-[rand(100000)].xml" />
```

## 其它數字格式化器

以下格式化器不如上一節中描述的格式化器常用。

### abs()

傳回數字屬性值的絕對值。

### and(value)

傳回兩個值的 AND 結果。兩邊提供的值必須是 1/0、yes/no 或 true/false。

* **value**：用於比較的布林值。

### ceiling()

傳回大於或等於數字屬性值的最小整數。

### currency(\[integer\_count])

傳回格式化為貨幣的數值。

* **count**：可選數字，指定小數點右側顯示的位數。預設值為 `2`。

### decimal(\[integer\_count])

傳回格式化為十進位制數的數值，並使用逗號分隔千位、百萬位等。

* **count**：可選數字，指定小數點右側顯示的位數。預設值為 `2`。

### div(\[value])

傳回數字屬性值除以參數指定值的結果。

* **value**：可選數值，用於除以數字屬性值。預設值為 `2`。

### divide(\[value])

傳回數字屬性值除以參數指定值的結果。

* **value**：可選數值，用於除以數字屬性值。預設值為 `2`。

### expr(expression)

計算自由形式的數學或邏輯運算式並傳回結果。不同於 `lessthan()` 或 `isequal()` 這類單一操作格式化器，`expr()` 可直接接受標準比較和邏輯運算子，因此是複合條件或多變數比較的首選方法。

* **expression**：自由形式運算式。

#### 支援的運算子

| 運算子    | 描述     |
| ------ | ------ |
| `+`    | 加法     |
| `-`    | 減法     |
| `*`    | 乘法     |
| `/`    | 除法     |
| `%`    | 取模（餘數） |
| `<`    | 小於     |
| `<=`   | 小於或等於  |
| `>`    | 大於     |
| `>=`   | 大於或等於  |
| `==`   | 等於     |
| `!=`   | 不等於    |
| `&&`   | 邏輯 AND |
| `\|\|` | 邏輯 OR  |

#### 範例

1. **用於 `<=` 檢查的等效鏈式格式化器和 `expr()` 方法**

   ```
   <!-- Using chained formatters -->
   [a | lessthan([b]) | or([a | equals([b])])]
   <!-- Using expr() -->
   [_ | expr("[a] <= [b]")]
   ```

   ```
   <arc:set attr="order.orderQty" value="5" />
   <arc:set attr="warehouse.stockLevel" value="10" />
   <arc:set attr="result.canFulfill" value="" />

   <arc:if exp="[_ | expr("[order.orderQty] <= [warehouse.stockLevel]")]">
     <arc:set attr="result.canFulfill" value="true" />
   <arc:else>
     <arc:set attr="result.canFulfill" value="false" />
   </arc:else>
   </arc:if>

   <arc:set attr="out.filename" value="order_fulfillment_result.txt" />
   <arc:set attr="out.data" value="canFulfill=[result.canFulfill]" />
   <arc:push item="out" />
   ```

   **預期輸出**

   將寫入名為 `order_fulfillment_result.txt` 的檔案，其內容為 `canFulfill=true`，並且傳出訊息標頭 `X-Can-Fulfill` 設定為 `true`。

2. **`>=` 檢查**

   ```
   <arc:set attr="data.score" value="85" />
   <arc:set attr="data.minimum" value="80" />
   <arc:set attr="data.target" value="85" />
   <arc:set attr="data.stretch" value="90" />
   <arc:set attr="_log.info" value="score >= minimum: [ | expr('[data.score] >= [data.minimum]')]" />
   <arc:set attr="_log.info" value=" score >= target: [ | expr('[data.score] >= [data.target]')]" />
   <arc:set attr="_log.info" value="score >= stretch: [ | expr('[data.score] >= [data.stretch]')]" />
   ```

   **預期輸出**

   * `score >= minimum: true`
   * `score >= target: true`
   * `score >= stretch: false`

3. **包含多個變數的複合條件**

   ```
   <arc:set attr="item.price" value="49.99" />
   <arc:set attr="item.minPrice" value="10" />
   <arc:set attr="item.maxPrice" value="500" />
   <arc:set attr="item.priceValid" value="" />

   <arc:if exp="[_ | expr("[item.price] >= [item.minPrice] && [item.price] <= [item.maxPrice]")]">
     <arc:set attr="item.priceValid" value="true" />
   <arc:else>
     <arc:set attr="item.priceValid" value="false" />
   </arc:else>
   </arc:if>
   ```

   **預期輸出**

   `priceValid = true`

4. **從 XML 輸入檔案讀取值**

   當 Script 端口處理傳入訊息時，訊息正文可透過 `[FilePath]` 存取。以下範例展示如何開啟該輸入，使用 `xpath()` 從中讀取值，然後使用 `expr()` 計算這些值。給定以下輸入訊息：

   ```xml theme={null}
   <Order>
     <Quantity>5</Quantity>
     <StockLevel>10</StockLevel>
   </Order>
   ```

   此指令碼讀取這些值並判斷訂單是否可以履行：

   ```
   <arc:set attr="order.orderQty" value="" />
   <arc:set attr="order.stockLevel" value="" />
   <arc:set attr="result.canFulfill" value="" />

   <arc:set attr="xml.uri" value="[FilePath]" />
   <arc:call op="xmlOpen" in="xml">
     <arc:set attr="order.orderQty" value="[xpath(Order/Quantity)]" />
     <arc:set attr="order.stockLevel" value="[xpath(Order/StockLevel)]" />
   </arc:call>

   <arc:if exp="[_ | expr("[order.orderQty] <= [order.stockLevel]")]">
     <arc:set attr="result.canFulfill" value="true" />
   <arc:else>
     <arc:set attr="result.canFulfill" value="false" />
   </arc:else>
   </arc:if>
   ```

   **預期輸出**

   `canFulfill = true`

<Note>使用算術或數值比較運算子時，運算式中引用的屬性必須包含數值。非數字字串可能會產生意外結果。</Note>

### floor()

傳回小於或等於數字屬性值的最大整數。

### format(pattern)

根據提供的模式和平臺行為格式化數值結果。

* **pattern**：要使用的格式化模式。

#### 範例

```
<arc:set attr="tmp" value="$1,440.123" />
[tmp]
<br>
[tmp | format("#.##")]
```

`tmp` 屬性被設定為 `$1,440.123`，並透過 `format("#.##")` 格式化器處理。結果為 **\$1440.12**。

```
<arc:set attr="rnd" value="1055.68" />
[rnd]
<br>
[rnd | format("#.#")]
```

`rnd` 屬性被設定為 `1055.68`，並透過 `format("#.#")` 格式化器處理。結果為 **1055.7**。

### isbetween(integer\_lowvalue, integer\_highvalue\[, ifbetween]\[, ifnotbetween])

如果屬性值大於或等於第一個參數值且小於或等於第二個參數值，則傳回 *true*（或 *ifbetween*）。否則傳回 *false*（或 *ifnotbetween*）。

* **lowvalue**：要檢查範圍的下限。
* **highvalue**：要檢查範圍的上限。
* **ifbetween**：可選值，如果屬性值大於或等於第一個參數值且小於或等於第二個參數值，則傳回此值。
* **ifnotbetween**：可選值，如果屬性值小於第一個參數值或大於第二個參數值，則傳回此值。

### isequal(value\[, ifequal]\[, ifnotequal])

如果屬性值等於參數值，則傳回 *true*（或 *ifequal*）。否則傳回 *false*（或 *ifnotequal*）。

* **value**：要與屬性值比較的數值。
* **ifequal**：可選值，如果屬性值等於參數值，則傳回此值。
* **ifnotequal**：可選值，如果屬性值不等於參數值，則傳回此值。

### modulus(value)

傳回數字屬性值除以指定參數值後的模數。

* **value**：用於除以屬性值的數字。

### number(value\[, format]\[, locale])

傳回格式化為十進位制數的數值。可選擇新增格式和區域設定。

* **format**：可選的十進位制數字格式。預設值為 `#.00`。可以使用以下特殊字元：

  | 字元  | 描述              |
  | --- | --------------- |
  | `0` | 數字              |
  | `#` | 數字；零顯示為空        |
  | `.` | 小數分隔符號或貨幣小數分隔符號 |
  | `-` | 負號              |
  | `,` | 分組分隔符號          |

* **locale**：區域設定資訊。預設值為不變區域性或區域設定，這意味著它不與特定國家或地區關聯。它接受語言標籤（例如 `en`、`fr`、`en-US`、`en-IN`、`fr-FR` 和 `zh-CN`）。

### or(value)

傳回兩個值的 OR 結果。兩邊提供的值必須是 1/0、yes/no 或 true/false。

* **value**：用於比較的布林值。

### percentage(\[integer\_count])

傳回格式化為百分比的數值。

* **count**：可選數字，表示小數點右側顯示的位數。

### pow(\[value])

傳回數字屬性值的指定參數值次冪。

* **value**：可選的冪，用於將屬性值提升到該冪。預設值為 `2`。

### round(\[integer\_value])

傳回數字屬性值，並按參數指定的小數位數進行舍入。

* **value**：可選的小數位數。預設值為 `2`。
* **rounding\_mode**：指定能夠丟棄精度的數值運算的舍入行為。可接受的值為：`Default`、`ToEven`、`AwayFromZero`、`ToZero`、`ToNegativeInfinity`、`ToPositiveInfinity`。使用的預設舍入策略取決於你的作業系統。.NET 使用 <a href="https://learn.microsoft.com/en-us/dotnet/api/system.midpointrounding?view=net-6.0" target="_blank">ToEven</a>，Java 使用 <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/math/RoundingMode.html#HALF_EVEN" target="_blank">Half Even</a>。

還可以指定全域 `RoundingMode` 環境變數，並將其中一個 `rounding_mode` 值作為其值。這樣做時，只要格式化器中未明確指定 `rounding_mode`，{siteNameShort} 就會使用該舍入模式。更具體地說，{siteNameShort} 會按以下順序檢查值：

1. `rounding_mode` 輸入
2. `RoundingMode` 環境變數
3. 如上所述，由作業系統確定的預設值

### sqrt()

傳回數字屬性值的平方根。

### subtract(\[value])

傳回數字屬性值與參數指定值之間的差值。

* **value**：可選數值，用於從屬性值中減去。預設值為 `1`。