README

一个用于处理任意精度数字的PHP库。

安装

此库可以通过 Composer 安装

composer require brick/math

要求

此库需要PHP 8.1或更高版本。

为了与PHP 8.0兼容，您可以使用版本 0.11。对于PHP 7.4，您可以使用版本 0.10。对于PHP 7.1、7.2和7.3，您可以使用版本 0.9。请注意，这些PHP版本已过时且不再受支持。如果您仍然在使用这些PHP版本之一，您应考虑尽快升级。

尽管此库可以在任何PHP安装上无缝工作，但强烈建议您安装 GMP 或 BCMath 扩展以加快计算速度。在运行时将自动选择最快的可用计算器实现。

项目状态和发布流程

虽然此库仍在开发中，但它经过充分测试，并被认为是足够稳定，可以用于生产环境。

当前发布版本编号为 0.x.y。当引入非破坏性更改（添加新方法、优化现有代码等）时，y 将增加。

当引入破坏性更改时，将始终启动新的 0.x 版本周期。

因此，将您的项目锁定到给定的发布周期，例如 ^0.12，是安全的。

如果您需要升级到新的发布周期，请检查 发布历史记录 以获取每个后续 0.x.0 版本引入的更改列表。

包内容

此库在 Brick\Math 命名空间中提供了以下公共类

• BigNumber：代表 BigInteger、BigDecimal 和 BigRational 的基类
• BigInteger：表示任意精度整数数字
• BigDecimal：表示任意精度小数数字
• BigRational：表示任意精度有理数（分数）
• RoundingMode：枚举表示所有可用的舍入模式

以及 Brick\Math\Exception 命名空间中的以下异常

• MathException：所有异常的基类
• DivisionByZeroException：在发生除以零时抛出
• IntegerOverflowException：在尝试将过大的 BigInteger 转换为 int 时抛出
• NumberFormatException：在解析格式无效的数字字符串时抛出
• RoundingNecessaryException：当操作结果无法表示而不进行显式舍入时抛出
• NegativeNumberException：尝试计算负数的平方根时抛出

概述

实例化

类构造函数不是公开的，您必须使用工厂方法来获取实例。

所有类都提供一个接受以下任何类型的 of() 工厂方法：

• BigNumber 实例
• int 数字
• float 数字
• 整数、小数和有理数的字符串表示形式

示例

BigInteger::of(123546);
BigInteger::of('9999999999999999999999999999999999999999999');

BigDecimal::of(1.2);
BigDecimal::of('9.99999999999999999999999999999999999999999999');

BigRational::of('2/3');
BigRational::of('1.1'); // 11/10

注意，所有 of() 方法接受上述所有表示，只要它可以安全地转换为当前类型

BigInteger::of('1.00'); // 1
BigInteger::of('1.01'); // RoundingNecessaryException

BigDecimal::of('1/8'); // 0.125
BigDecimal::of('1/3'); // RoundingNecessaryException

关于原生整数的说明：从 int 实例化是安全的，只要您不超过您平台的最大值（PHP_INT_MAX）。在这种情况下，PHP 将会无声地将它转换为 float，这可能会导致信息丢失。如有疑问，请优先使用字符串实例化，它支持无限位数的数字。

echo BigInteger::of(999999999999999999999); // 1000000000000000000000
echo BigInteger::of('999999999999999999999'); // 999999999999999999999

关于浮点数的说明：从 float 实例化可能是不安全的，因为浮点数按设计是不精确的，可能会丢失信息。始终优先使用字符串实例化，它支持无限位数的数字。

echo BigDecimal::of(1.99999999999999999999); // 2
echo BigDecimal::of('1.99999999999999999999'); // 1.99999999999999999999

不可变性与链式调用

BigInteger、BigDecimal 和 BigRational 类是不可变的：它们的值永远不会改变，因此可以安全地传递。所有返回 BigInteger、BigDecimal 或 BigRational 的方法都会返回一个新的对象，而不会影响原始对象。

$ten = BigInteger::of(10);

echo $ten->plus(5); // 15
echo $ten->multipliedBy(3); // 30

方法可以链式调用以提高可读性。

echo BigInteger::of(10)->plus(5)->multipliedBy(3); // 45

参数类型

所有接受数字的方法：plus()、minus()、multipliedBy() 等，接受与 of() 相同的类型。例如，给定以下数字

$integer = BigInteger::of(123);

以下行是等效的

$integer->multipliedBy(123);
$integer->multipliedBy('123');
$integer->multipliedBy($integer);

与 of() 一样，其他类型的 BigNumber 也是可接受的，只要它们可以安全地转换为当前类型。

echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.0')); // 4
echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.5')); // RoundingNecessaryException
echo BigDecimal::of(2.5)->multipliedBy(BigInteger::of(2)); // 5.0

除法与舍入

BigInteger

默认情况下，除以 BigInteger 返回除法的精确结果，或者在除法的余数不为零时抛出异常。

echo BigInteger::of(999)->dividedBy(3); // 333
echo BigInteger::of(1000)->dividedBy(3); // RoundingNecessaryException

您可以选择传递一个可选的 舍入模式 来舍入结果，如果需要的话。

echo BigInteger::of(1000)->dividedBy(3, RoundingMode::DOWN); // 333
echo BigInteger::of(1000)->dividedBy(3, RoundingMode::UP); // 334

如果您对商和余数感兴趣，也有方法可以获取它们。

echo BigInteger::of(1000)->quotient(3); // 333
echo BigInteger::of(1000)->remainder(3); // 1

您甚至可以同时获取它们。

[$quotient, $remainder] = BigInteger::of(1000)->quotientAndRemainder(3);

BigDecimal

除以 BigDecimal 总是需要指定一个刻度。如果除法的精确结果不适合给定的刻度，则必须提供一个 舍入模式。

echo BigDecimal::of(1)->dividedBy('8', 3); // 0.125
echo BigDecimal::of(1)->dividedBy('8', 2); // RoundingNecessaryException
echo BigDecimal::of(1)->dividedBy('8', 2, RoundingMode::HALF_DOWN); // 0.12
echo BigDecimal::of(1)->dividedBy('8', 2, RoundingMode::HALF_UP); // 0.13

如果您知道除法产生有限的小数位数，则可以使用 exactlyDividedBy()，它会自动计算所需的刻度以适应结果，或者如果除法产生无限循环小数则抛出异常。

echo BigDecimal::of(1)->exactlyDividedBy(256); // 0.00390625
echo BigDecimal::of(1)->exactlyDividedBy(11); // RoundingNecessaryException

BigRational

BigRational 的除法结果始终可以精确表示。

echo BigRational::of('123/456')->dividedBy('7'); // 123/3192
echo BigRational::of('123/456')->dividedBy('9/8'); // 984/4104

位运算

BigInteger 支持位运算

• and()
• or()
• xor()
• not()

位运算和位移

• shiftedLeft()
• shiftedRight()

序列化

BigInteger、BigDecimal 和 BigRational 可以在机器上安全序列化，并在另一台机器上反序列化，即使这些机器没有共享相同的 PHP 扩展集。

例如，在支持GMP的机器上进行序列化，在未安装此扩展的机器上进行反序列化，仍将按预期工作。