Math Builtins

数学函数 / Math Built-ins

怎么调用 / How to Call

数学函数是全局函数，直接写名字加括号：

Math functions are global functions; write the name and parentheses:

double a = abs(-5);
double b = max(3, 7);
double c = sqrt(2.0);

参数类型是数字（int 或 double），返回类型多数是 double——即使输入是整数。需要整数时用 toInt：

Arguments are numbers (int or double); returns are mostly double — even from integer input. Convert with toInt when an integer is needed:

int n = toInt(floor(3.7));      // 3

---

基础 / Basics

abs(-5)             // 5，绝对值
fabs(-5.5)          // 5.5，浮点绝对值
max(3, 7)           // 7
min(3, 7)           // 3
fmod(7.5, 2.0)      // 1.5，浮点取余

max / min 保持参数类型：两个 int 返回 int，否则返回 double。

max / min keep the argument type: two ints give int; otherwise double.

---

幂与根 / Powers and Roots

pow(2, 10)          // 1024.0
sqrt(16.0)          // 4.0
cbrt(27.0)          // 3.0
hypot(3.0, 4.0)     // 5.0，即 sqrt(3² + 4²)

hypot 是直角三角形斜边，比手写 sqrt(a*a + b*b) 更稳定（避免中间结果溢出）。

hypot computes the hypotenuse of a right triangle, more stable than sqrt(a*a + b*b) (avoids intermediate overflow).

---

取整 / Rounding

ceil(3.2)           // 4.0，向上
floor(3.8)          // 3.0，向下
round(3.5)          // 4，四舍五入（返回 long）
rint(3.5)           // 4.0，银行家舍入（四舍六入五成双）

round 返回 long，其他取整函数返回 double。

round returns long; the others return double.

---

三角 / Trigonometry

sin(0.0)            // 0.0
cos(0.0)            // 1.0
tan(0.0)            // 0.0
asin(1.0)           // π/2
acos(1.0)           // 0.0
atan(1.0)           // π/4
atan2(1.0, 1.0)     // π/4，用两个参数确定象限

所有三角函数的参数是弧度，不是角度。角度要转：

All trigonometric functions take radians, not degrees. Convert:

double rad = toRadians(90.0);       // 1.5708...
sin(rad)                            // 1.0
double deg = toDegrees(3.14159);    // 180.0 左右

atan2(y, x) 比 atan(y/x) 更安全——它能处理 x == 0 和各种象限。

atan2(y, x) is safer than atan(y/x) — it handles x == 0 and all quadrants.

---

对数与指数 / Logarithms and Exponentials

log(2.718)          // ≈ 1.0，自然对数
log10(1000.0)       // 3.0，以 10 为底
log2(8.0)           // 3.0，以 2 为底
exp(1.0)            // ≈ 2.718

log2 在计算二进制位数时很常用：

log2 is useful for binary bit-width calculations:

int bits = toInt(ceil(log2(255.0)));    // 8

---

随机 / Randomness

rand 返回随机数：

rand returns random numbers:

rand()              // 0.0 到 1.0 之间的 double
rand(1, 6)          // 1 到 6 之间的整数（模拟骰子）
rand(0.0, 1.0)      // 0.0 到 1.0 之间的 double

两个参数时，类型决定返回类型：两个整数返回 int，否则返回 double。

With two arguments, types decide the result: two ints give int; otherwise double.

randChoose 从若干参数中随机取一个：

randChoose picks one at random:

string color = randChoose("红", "绿", "蓝");
int n = randChoose(10, 20, 30, 40);

---

什么时候需要数学函数 / When You Need Math

日常脚本很少做复杂计算。常见场景：

Everyday scripts rarely do heavy math. Common cases:

• 距离：sqrt(dx*dx + dy*dy) 或 hypot(dx, dy)。

• 概率：rand() < 0.3 表示 30% 概率。

• 等级曲线：toInt(100 * pow(1.1, level))。

• 角度：从玩家的 yaw 计算朝向。

• Distance: hypot(dx, dy).

• Probability: rand() < 0.3 for a 30% chance.

• Level curves: toInt(100 * pow(1.1, level)).

• Angles: compute direction from a player's yaw.

遇到不确定的函数时，先查官方 Java Math 文档——HimDSL 的数学函数一一对应。

When unsure, check the official Java Math docs — HimDSL's math functions map one-to-one.

---

其他函数 / Less Common

还有一些低频函数，日常几乎用不到，列在此供参考：

A few low-frequency functions, listed for reference:

expm1(x)            // exp(x) - 1，精度更好
log1p(x)            // log(1 + x)，精度更好
sinh, cosh, tanh    // 双曲函数
signum(x)           // 符号：-1 / 0 / 1
copySign(a, b)      // 返回 |a| 带 b 的符号
nextUp(x), nextDown(x)  // 相邻浮点数
getExponent(x)      // 浮点指数位
IEEEremainder(a, b) // IEEE 754 取余
floorDiv(a, b)      // 向下取整的整数除法
floorMod(a, b)      // 向下取整的取模
toIntExact(l)       // long 转 int，溢出报错
ulp(x)              // 单位最后一位
fma(a, b, c)        // a*b + c 融合乘加

不需要背它们。用到时查文档，或看这里。

No need to memorize. Look them up when needed.

---

小结 / Summary

• 数学函数直接调用，返回类型多为 double。

• 基础：abs / max / min。

• 幂与根：pow / sqrt / cbrt / hypot。

• 取整：ceil / floor / round。

• 三角：参数是弧度，用 toRadians / toDegrees 转换。

• 随机：rand() / rand(a, b) / randChoose(...)。

• 不确定的函数查 Java Math 文档。

• Call math functions directly; results are mostly double.

• Basics: abs / max / min.

• Powers and roots: pow / sqrt / cbrt / hypot.

• Rounding: ceil / floor / round.

• Trig: arguments are radians; convert with toRadians / toDegrees.

• Randomness: rand() / rand(a, b) / randChoose(...).

• Unsure? Check Java's Math docs.

---

下一步 / Next Steps

下一章 [高精度计算 / BigDecimal-Builtins] 讲什么时候普通浮点不够用，以及替代方案。

Next, [高精度计算 / BigDecimal-Builtins] covers when normal floats are not enough and what to use instead.

---