墨灵知识库

Appearance

构造函数与输入 ​

Decimal 是一个构造函数，接受一个参数：number、string、bigint 或 Decimal 实例。
也可不带 new 直接调用（Decimal(1) 等价于 new Decimal(1)）。

1. 基本用法 ​

js
const x = new Decimal(123.4567)          // number
const y = new Decimal('123456.7e-3')     // string（科学计数法）
const z = new Decimal(123456789012345678901234567890n)  // bigint
const w = new Decimal(x)                 // 从 Decimal 构造（复制）

Decimal.isDecimal(value) 可判断一个值是否为 Decimal 实例：

js
Decimal.isDecimal(new Decimal(1))        // true
Decimal.isDecimal(1)                     // false
Decimal.isDecimal('1')                   // false

2. 接受的字符串格式 ​

格式示例结果
普通十进制'123.45'123.45
科学计数法'1.23e+5' / '123456.7e-3'123000 / 123.4567
前导/后缀小数点'.5' / '5.'0.5 / 5
正负号'+1.5' / '-1.5'1.5 / -1.5
下划线分隔'2_147_483_647'2147483647
十六进制（前缀 0x）'0xff.f'255.9375
二进制（前缀 0b）'0b10101100'172
八进制（前缀 0o）'0o17'15
二进制指数形式（p）'0b1.1111111111111111111111111111111111111111111111111111p+1023'1.7976931348623157081e+308（Number.MAX_VALUE 量级）
特殊值'NaN' / 'Infinity' / '-Infinity'NaN / Infinity / -Infinity
js
// 进制混算
new Decimal('0xff.f').plus('0b10101100')     // '427.9375'

NOTE

  • 十六进制字符串也可用 p 指数（如 '0x1p+4' = 16），类似 JS 的十六进制浮点字面量。
  • 字符串中的下划线仅作可读性分隔，可任意放置（如 '2_147_483_647'）。
  • 字符串解析不丢失精度，这是推荐传入方式。

3. number 输入的精度损失 ​

number 参数会先转为十进制字符串再解析，因此字面量本身被 JS 舍入过的值无法还原：

js
new Decimal(1.0000000000000001)         // '1'
new Decimal(88259496234518.57)          // '88259496234518.56'
new Decimal(99999999999999999999)       // '100000000000000000000'
new Decimal(2e+308)                     // 'Infinity'（溢出）
new Decimal(1e-324)                     // '0'（下溢）
new Decimal(0.7 + 0.1)                  // '0.7999999999999999'

普通字面量（15 位有效数字以内）不受影响：

js
new Decimal(1.005).toString()           // '1.005'

TIP

超过 15 位有效数字、来自浮点运算结果、或需要精确表示的值 → 一律传字符串。

4. bigint 输入 ​

js
new Decimal(123456789012345678901234567890n).toString()
// '1.2345678901234567890123456789e+29'

bigint 会先转成十进制字符串再解析，因此可以精确表示任意大的整数（但受 precision 与 maxE 影响）。

5. 无效输入 → 抛错 ​

输入类型或格式不合法时抛出错误，消息前缀为 [DecimalError]：

js
new Decimal(true)         // 抛错：[DecimalError] Invalid argument: true
new Decimal({})           // 抛错：[DecimalError] Invalid argument: [object Object]
new Decimal('abc')        // 抛错：[DecimalError] Invalid argument: abc
new Decimal('1.2.3')      // 抛错：[DecimalError] Invalid argument: 1.2.3
new Decimal(null)         // 抛错：[DecimalError] Invalid argument: null
new Decimal(undefined)    // 抛错：[DecimalError] Invalid argument: undefined

NOTE

与许多 API 不同，null/undefined 不是合法的空值输入，会直接抛错。

6. NaN 与 Infinity 是合法值 ​

js
new Decimal(NaN).toString()          // 'NaN'
new Decimal(Infinity).toString()     // 'Infinity'
new Decimal('-Infinity').toString()  // '-Infinity'
new Decimal(NaN).isNaN()             // true
new Decimal(Infinity).isFinite()     // false

7. 指数范围限制（minE / maxE） ​

超出指数范围的值在构造时即溢出/下溢：

js
new Decimal('1e9000000000000001')    // 'Infinity'（超过 maxE = 9e15）
new Decimal('1e-9000000000000001')   // '0'（低于 minE = -9e15）

8. 从运算结果构造 ​

任何返回 Decimal 的方法结果都可以直接再参与构造或运算（内部会复制，且跨构造器运算会自动转换）：

js
new Decimal(1).plus(new Decimal(2)).times('3')   // '9'

关于跨构造器（clone 出来的）运算，见 配置与舍入模式。

相关章节 ​