> For the complete documentation index, see [llms.txt](https://ultimateshop.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ultimateshop.superiormc.cn/ultimateshop-wen-dang/pei-zhi-ge-shi/math-calculate-format.md).

# ➗数学计算格式

和多数插件不同，UltimateShop 允许在几乎所有填数字的地方使用 PlaceholderAPI 和数学计算格式，价格、购买/出售次数上限之类都能随心配置。

{% hint style="info" %}
使用该功能需先在 `config.yml` 中开启 `math.enabled`。
{% endhint %}

## 结果精度

`math.scale` 控制数学结果保留几位小数，UltimateShop 采用 `HALF_UP` 舍入。乘倍率同样算一次数学计算，所以乘出来的结果（包括出售价格修正、预览和最终收益）也按这个位数处理。

```yaml
math:
  scale: 2
```

例如 `scale: 2` 时，`10` 乘以 `0.333333` 得到 `3.33`。

## 数学计算格式一览

`max` - 比较两个数并返回较大的那个。 (`max(4,5)`)

`min` - 比较两个数并返回较小的那个。 (`min(4,5)`)

`()` - 括号，里面的内容优先计算 (`3 * (4 + 1)`)

`$` - 声明变量 (`$1 / 3`)

`e` - 欧拉常数 (`log(e)`)

`pi` - 圆周率 (`sin(pi)`)

`+` - 两数相加 (`1 + 1`)

`-` - 两数相减，或对一个数取负 (`3-2`、`-(4+2)`)

`/` - 两数相除 (`3 / 4`)

`*` - 两数相乘 (`2 * 3`)

`^` - 求幂 (`3^3`)

`%` - 取模（相除的余数） (`7 % 4`)

`abs` - 取数字的绝对值 (`abs$1`, `abs-1`)

`round` - 四舍五入到最接近的整数（`round1.5`、`round(2.3)`）

`ceil` - 向上取整 (`ceil1.05`)

`floor` - 向下取整 (`floor0.95`)

`rand` - 生成 0 到指定上限之间的随机数 (`rand4`)

`log` - 取自然对数 (`log(e)`)

`sqrt` - 取平方根 (`sqrt4`)

`cbrt` - 取立方根 (`cbrt(8)`)

`sin` - 取正弦 (`sin$2`)

`cos` - 取余弦 (`cos(2*pi)`)

`tan` - 取正切 (`tanpi`)

`asin` - 取反正弦 (`asin$2`)

`acos` - 取反余弦 (`acos0.45`)

`atan` - 取反正切 (`atan1`)

`sinh` - 取双曲正弦 (`sinh(4)`)

`cosh` - 取双曲余弦 (`cosh(4)`)

`true` - 代表 1 的布尔常量

`false` - 代表 0 的布尔常量

`=` - 判断两数是否相等（`1 = 1` 得 `1`，`1 = 3` 得 `0`），也可写作 `==`

`!=` - 判断两数是否不等（`1 != 2` 得 `1`，`1 != 1` 得 `0`）

`>` - 判断前者是否大于后者 (`1 > 0`)

`<` - 判断前者是否小于后者 (`0 < 1`)

`>=` - 判断前者是否大于或等于后者 (`1 >= 1`)

`<=` - 判断前者是否小于或等于后者 (`0 <= 1`)

`|` - 逻辑或 (`true | false`)，也可写作 `||`

`&` - 逻辑与 (`true & true`)，也可写作 `&&`

`!` - 逻辑非 (`!true`)

## 函数

数学表达式系统内置了几个常用函数，涵盖求和、取最大/最小值、平均值和随机数。

在 `config.yml` 中开启下面这项后，这些函数才可用：

```yaml
math:
  enable-function: true
```

关闭时不会注册这些自定义数学函数。

### 可用函数

#### `sum`

返回所有参数的总和。

**语法**

```
sum(number1, number2, ...)
```

**示例**

```
sum(1, 2, 3)
```

结果：

```
6
```

```
sum(10, -3, 2.5)
```

结果：

```
9.5
```

不传参数时结果为 `0`：

```
sum()
```

结果：

```
0
```

***

#### `max`

返回所有参数中最大的那个。

**语法**

```
max(number1, number2, ...)
```

**示例**

```
max(5, 12, 8)
```

结果：

```
12
```

```
max(-10, -3, -20)
```

结果：

```
-3
```

不传参数时结果为 `0`：

```
max()
```

结果：

```
0
```

***

#### `min`

返回所有参数中最小的那个。

**语法**

```
min(number1, number2, ...)
```

**示例**

```
min(5, 12, 8)
```

结果：

```
5
```

```
min(-10, -3, -20)
```

结果：

```
-20
```

不传参数时结果为 `0`：

```
min()
```

结果：

```
0
```

***

#### `avg`

返回所有参数的算术平均值。

它先把所有参数相加，再除以参数个数。

**语法**

```
avg(number1, number2, ...)
```

**示例**

```
avg(10, 20, 30)
```

结果：

```
20
```

```
avg(2, 3, 7)
```

结果：

```
4
```

不传参数时结果为 `0`：

```
avg()
```

结果：

```
0
```

***

#### `random`

生成一个随机小数。

具体行为取决于传入几个参数。

### `random()`

返回 `0`（含）到 `1`（不含）之间的随机小数。

**示例**

```
random()
```

可能的结果包括：

```
0.137
0.5
0.999
```

结果满足以下范围：

```
0 <= result < 1
```

### `random(max)`

返回 `0` 到所给值之间的随机小数。

**示例**

```
random(10)
```

结果满足：

```
0 <= result < 10
```

还支持负值：

```
random(-10)
```

结果满足：

```
-10 <= result < 0
```

所给值为 `0` 时，结果恒为 `0`：

```
random(0)
```

结果：

```
0
```

### `random(min, max)`

返回两个值之间的随机小数。

**示例**

```
random(5, 10)
```

结果满足：

```
5 <= result < 10
```

参数顺序无关紧要，函数会自动判断哪个更小：

```
random(10, 5)
```

等价于：

```
random(5, 10)
```

两个值相等时直接返回该值：

```
random(5, 5)
```

结果：

```
5
```

传入超过两个参数时，只取前两个：

```
random(1, 10, 100)
```

等价于：

```
random(1, 10)
```

> 随机区间的上限不含在内。例如 `random(1, 5)` 会返回大于等于 `1` 的值，但不会正好返回 `5`。

### 函数一览

| 函数                 | 说明                    | 无参数时 |
| ------------------ | --------------------- | ---: |
| `sum(...)`         | 所有参数求和                |  `0` |
| `max(...)`         | 返回最大的参数               |  `0` |
| `min(...)`         | 返回最小的参数               |  `0` |
| `avg(...)`         | 返回算术平均值               |  `0` |
| `random()`         | 返回 `0` 到 `1` 的随机值     |  随机值 |
| `random(max)`      | 返回 `0` 到 `max` 之间的随机值 |  不适用 |
| `random(min, max)` | 返回两个值之间的随机值           |  不适用 |
