README

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

有关类和方法列表的完整信息，请查看API 文档。

安装

此库可通过 Composer 安装。只需在您的 composer.json 文件中定义以下要求即可

{
    "require": {
        "asika/math": "0.7.*"
    }
}

要求

此库需要 PHP 5.3、PHP 7 或 HHVM。

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

项目状态 & 发布流程

虽然此库仍在开发中，但经过充分测试，应足够稳定以在生产环境中使用。

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

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

因此，可以将项目锁定到给定的版本周期，例如 0.7.*。

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

包内容

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

BigNumber：是 BigInteger、BigDecimal 和 BigRational 的基类
BigInteger：表示任意精度整数
BigDecimal：表示任意精度十进制数
BigRational：表示任意精度有理数（分数）
RoundingMode：包含舍入模式的常量。

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

ArithmeticException：所有异常的基类
DivisionByZeroException：在除以零时抛出
NumberFormatException：在解析无效格式的数字字符串时抛出
RoundingNecessaryException：在操作结果无法不进行显式舍入的情况下抛出

概述

实例化

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

所有类都提供了一个接受以下任何类型的 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'); // ArithmeticException

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

关于原生整数：从 int 实例化是安全的，只要您不超过平台的最大值 (PHP_INT_MAX)，否则 PHP 会无提示将其透明地转换为 float，可能导致信息丢失。如有疑问，请优先选择从 string 实例化，它支持无限位数的数字。

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

关于浮点值：从 float 实例化可能是不安全的，因为浮点值设计上是不精确的，可能导致信息丢失。始终优先从 string 实例化，它支持无限位数的数字。

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')); // ArithmeticException
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

您甚至可以同时获取两者。

list ($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、BigDecimal 和 BigRational 可以在机器上安全序列化，并在另一台机器上反序列化，即使这些机器不共享相同的 PHP 扩展集。

例如，在支持 GMP 的机器上序列化，并在没有安装此扩展的机器上反序列化，仍然可以按预期工作。

asika / math

维护者

详细信息