> ## 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`。