BigDecimal

在 JavaScript 中，数字通常以 64 位浮点值存储。虽然浮点数快速且多功能，但它们可能引入小的舍入误差。这些误差在日常使用中往往难以察觉，但在金融或统计等领域可能会成为问题，因为小的不准确性可能随时间导致更大的差异。

通过使用 BigDecimal 模块，您可以避免这些问题并以更高的精度执行计算。

BigDecimal 数据类型可以表示具有大量小数位的实数，防止浮点数学的常见错误（例如，0.1 + 0.2 ≠ 0.3）。

BigDecimal 的工作原理

BigDecimal 使用两个组件来表示数字：

1. value：存储数字位数的 BigInt。
2. scale：确定小数点位置的 64 位整数。

BigDecimal 表示的数字计算为：value x 10^-scale。

• 如果 scale 为零或正数，它指定小数点右侧的位数。
• 如果 scale 为负数，value 乘以 10 的负 scale 次幂。

例如：

• value = 12345n 和 scale = 2 的 BigDecimal 表示 123.45。
• value = 12345n 和 scale = -2 的 BigDecimal 表示 1234500。

最大精度很大但不是无限的，限制为 2⁶³ 个小数位。

创建 BigDecimal

make

make 函数通过指定 BigInt 值和 scale 来创建 BigDecimal。scale 确定小数点右侧的位数。

示例（使用指定 Scale 创建 BigDecimal）

import { BigDecimal } from "effect"

// 从 BigInt (1n) 创建一个 scale 为 2 的 BigDecimal
const decimal = BigDecimal.make(1n, 2)

console.log(decimal)
// 输出: { _id: 'BigDecimal', value: '1', scale: 2 }

// 将 BigDecimal 转换为字符串
console.log(String(decimal))
// 输出: BigDecimal(0.01)

// 将 BigDecimal 格式化为标准十进制字符串
console.log(BigDecimal.format(decimal))
// 输出: 0.01

// 将 BigDecimal 转换为指数表示法
console.log(BigDecimal.toExponential(decimal))
// 输出: 1e-2

fromBigInt

fromBigInt 函数从 bigint 创建 BigDecimal。scale 默认为 0，意味着数字没有小数部分。

示例（从 BigInt 创建 BigDecimal）

import { BigDecimal } from "effect"

const decimal = BigDecimal.fromBigInt(10n)

console.log(decimal)
// 输出: { _id: 'BigDecimal', value: '10', scale: 0 }

fromString

将数字字符串解析为 BigDecimal。返回 Option<BigDecimal>：

• 如果字符串有效，返回 Some(BigDecimal)。
• 如果字符串无效，返回 None。

示例（将字符串解析为 BigDecimal）

import { BigDecimal } from "effect"

const decimal = BigDecimal.fromString("0.02")

console.log(decimal)
/*
输出:
{
  _id: 'Option',
  _tag: 'Some',
  value: { _id: 'BigDecimal', value: '2', scale: 2 }
}
*/

unsafeFromString

unsafeFromString 函数是 fromString 的变体，如果输入字符串无效会抛出错误。仅在您确信输入始终有效时使用此函数。

示例（字符串的不安全解析）

import { BigDecimal } from "effect"

const decimal = BigDecimal.unsafeFromString("0.02")

console.log(decimal)
// 输出: { _id: 'BigDecimal', value: '2', scale: 2 }

unsafeFromNumber

从 JavaScript number 创建 BigDecimal。对于非有限数字（NaN、+Infinity 或 -Infinity）会抛出 RangeError。

示例（数字的不安全解析）

import { BigDecimal } from "effect"

console.log(BigDecimal.unsafeFromNumber(123.456))
// 输出: { _id: 'BigDecimal', value: '123456', scale: 3 }

避免直接转换

避免将浮点数直接转换为 BigDecimal，因为它们的表示可能已经引入精度问题。

基本算术运算

BigDecimal 模块支持各种算术运算，提供精度并避免标准 JavaScript 算术中常见的舍入错误。以下是支持的运算列表：

函数	描述
sum	将两个 BigDecimal 值相加。
subtract	从一个 BigDecimal 值中减去另一个。
multiply	将两个 BigDecimal 值相乘。
divide	将一个 BigDecimal 值除以另一个，返回 Option<BigDecimal>。
unsafeDivide	将一个 BigDecimal 值除以另一个，如果除数为零则抛出错误。
negate	对 BigDecimal 值取反（即改变其符号）。
remainder	返回一个 BigDecimal 值除以另一个的余数，返回 Option<BigDecimal>。
unsafeRemainder	返回一个 BigDecimal 值除以另一个的余数，如果除数为零则抛出错误。
sign	返回 BigDecimal 值的符号（-1、0 或 1）。
abs	返回 BigDecimal 的绝对值。

示例（使用 BigDecimal 执行基本算术运算）

import { BigDecimal } from "effect"

const dec1 = BigDecimal.unsafeFromString("1.05")
const dec2 = BigDecimal.unsafeFromString("2.10")

// 加法
console.log(String(BigDecimal.sum(dec1, dec2)))
// 输出: BigDecimal(3.15)

// 乘法
console.log(String(BigDecimal.multiply(dec1, dec2)))
// 输出: BigDecimal(2.205)

// 减法
console.log(String(BigDecimal.subtract(dec2, dec1)))
// 输出: BigDecimal(1.05)

// 除法（安全，返回 Option<BigDecimal>）
console.log(BigDecimal.divide(dec2, dec1))
/*
输出:
{
  _id: 'Option',
  _tag: 'Some',
  value: { _id: 'BigDecimal', value: '2', scale: 0 }
}
*/

// 除法（不安全，如果除数为零则抛出错误）
console.log(String(BigDecimal.unsafeDivide(dec2, dec1)))
// 输出: BigDecimal(2)

// 取反
console.log(String(BigDecimal.negate(dec1)))
// 输出: BigDecimal(-1.05)

// 取模（不安全，如果除数为零则抛出错误）
console.log(
  String(
    BigDecimal.unsafeRemainder(dec2, BigDecimal.unsafeFromString("0.6"))
  )
)
// 输出: BigDecimal(0.3)

使用 BigDecimal 进行算术运算有助于避免 JavaScript 中浮点数常见的不准确性。例如：

示例（避免浮点数错误）

const dec1 = 1.05
const dec2 = 2.1

console.log(String(dec1 + dec2))
// 输出: 3.1500000000000004

比较运算

BigDecimal 模块提供了几个用于比较十进制值的函数。这些函数允许您确定两个值的相对顺序、找到最小值或最大值，并检查特定属性，如正负性或整数状态。

比较函数

函数	描述
lessThan	检查第一个 BigDecimal 是否小于第二个。
lessThanOrEqualTo	检查第一个 BigDecimal 是否小于或等于第二个。
greaterThan	检查第一个 BigDecimal 是否大于第二个。
greaterThanOrEqualTo	检查第一个 BigDecimal 是否大于或等于第二个。
min	返回两个 BigDecimal 值中较小的一个。
max	返回两个 BigDecimal 值中较大的一个。

示例（比较两个 BigDecimal 值）

import { BigDecimal } from "effect"

const dec1 = BigDecimal.unsafeFromString("1.05")
const dec2 = BigDecimal.unsafeFromString("2.10")

console.log(BigDecimal.lessThan(dec1, dec2))
// 输出: true

console.log(BigDecimal.lessThanOrEqualTo(dec1, dec2))
// 输出: true

console.log(BigDecimal.greaterThan(dec1, dec2))
// 输出: false

console.log(BigDecimal.greaterThanOrEqualTo(dec1, dec2))
// 输出: false

console.log(BigDecimal.min(dec1, dec2))
// 输出: { _id: 'BigDecimal', value: '105', scale: 2 }

console.log(BigDecimal.max(dec1, dec2))
// 输出: { _id: 'BigDecimal', value: '210', scale: 2 }

比较谓词

该模块还包括用于检查 BigDecimal 特定属性的谓词：

谓词	描述
isZero	检查值是否恰好为零。
isPositive	检查值是否为正数。
isNegative	检查值是否为负数。
between	检查值是否在指定范围内（包含边界）。
isInteger	检查值是否为整数（即没有小数部分）。

示例（检查 BigDecimal 值的符号和属性）

import { BigDecimal } from "effect"

const dec1 = BigDecimal.unsafeFromString("1.05")
const dec2 = BigDecimal.unsafeFromString("-2.10")

console.log(BigDecimal.isZero(BigDecimal.unsafeFromString("0")))
// 输出: true

console.log(BigDecimal.isPositive(dec1))
// 输出: true

console.log(BigDecimal.isNegative(dec2))
// 输出: true

console.log(
  BigDecimal.between({
    minimum: BigDecimal.unsafeFromString("1"),
    maximum: BigDecimal.unsafeFromString("2")
  })(dec1)
)
// 输出: true

console.log(
  BigDecimal.isInteger(dec2),
  BigDecimal.isInteger(BigDecimal.fromBigInt(3n))
)
// 输出: false true

规范化和相等性

在某些情况下，两个 BigDecimal 值可能具有不同的内部表示，但仍然表示相同的数字。

例如，1.05 可以用不同的 scale 在内部表示，例如：

• scale 为 2 的 105n
• scale 为 3 的 1050n

为了确保一致性，您可以规范化 BigDecimal 以调整 scale 并删除尾随零。

规范化

BigDecimal.normalize 函数调整 BigDecimal 的 scale 并消除其内部表示中任何不必要的尾随零。

示例（规范化 BigDecimal）

import { BigDecimal } from "effect"

const dec = BigDecimal.make(1050n, 3)

console.log(BigDecimal.normalize(dec))
// 输出: { _id: 'BigDecimal', value: '105', scale: 2 }

相等性

要检查两个 BigDecimal 值在数值上是否相等，无论其内部表示如何，请使用 BigDecimal.equals 函数。

示例（检查相等性）

import { BigDecimal } from "effect"

const dec1 = BigDecimal.make(105n, 2)
const dec2 = BigDecimal.make(1050n, 3)

console.log(BigDecimal.equals(dec1, dec2))
// 输出: true