内容

名称

Math::BigInt::Lib - Math::BigInt 库的虚拟父类

概要

# In the backend library for Math::BigInt et al.

package Math::BigInt::MyBackend;

use Math::BigInt::Lib;
our @ISA = qw< Math::BigInt::Lib >;

sub _new { ... }
sub _str { ... }
sub _add { ... }
str _sub { ... }
...

# In your main program.

use Math::BigInt lib => 'MyBackend';

描述

此模块提供对大整数计算的支持。它不打算直接使用，而是作为 Math::BigInt、Math::BigFloat、Math::BigRat 和相关模块使用的后端库的父类。

其他后端库包括 Math::BigInt::Calc、Math::BigInt::FastCalc、Math::BigInt::GMP 和 Math::BigInt::Pari。

为了允许使用多个大整数库，Math::BigInt 被重写为使用一个插件库来实现核心数学例程。任何符合 API 的模块都可以通过在程序中使用以下代码来被 Math::BigInt 使用

use Math::BigInt lib => 'libname';

'libname' 可以是完整的名称，例如 'Math::BigInt::Pari'，也可以是简短的版本，例如 'Pari'。

一般说明

库只需要处理无符号的大整数。输入参数有效性的测试由调用者完成，因此无需担心下溢（例如，在 _sub() 和 _dec() 中）或除以零（例如，在 _div() 和 _mod() 中）或类似情况。

一些库使用不修改其参数的方法，而一些库甚至不使用对象，而是使用未祝福的引用。因此，库方法始终被调用为类方法，而不是实例方法

$x = Class -> method($x, $y);     # like this
$x = $x -> method($y);            # not like this ...
$x -> method($y);                 # ... or like this

以及布尔方法

$bool = Class -> method($x, $y);  # like this
$bool = $x -> method($y);         # not like this

返回值始终是对象、字符串、Perl 标量或比较例程的真/假值。

API 版本

CLASS->api_version()

此方法不再使用，可以省略。子类未实现的方法将从该类继承。

构造函数

以下方法是强制性的：_new()、_str()、_add() 和 _sub()。但是，如果没有 _mul() 和 _div()，计算将非常慢。

CLASS->_new(STR)

将表示无符号十进制数的字符串转换为表示相同数字的对象。输入已规范化，即它与 ^(0|[1-9]\d*)$ 匹配。

CLASS->_zero()

返回表示数字零的对象。

CLASS->_one()

返回表示数字一的对象。

CLASS->_two()

返回表示数字二的对象。

CLASS->_ten()

返回表示数字十的对象。

CLASS->_from_bin(STR)

给定表示二进制数的字符串，返回一个对象。输入带有 '0b' 前缀，并与正则表达式 ^0[bB](0|1[01]*)$ 匹配。

CLASS->_from_oct(STR)

给定表示八进制数的字符串，返回一个对象。输入带有 '0' 前缀，并与正则表达式 ^0[1-7]*$ 匹配。

CLASS->_from_hex(STR)

给定表示十六进制数的字符串，返回一个对象。输入带有 '0x' 前缀，并与正则表达式 ^0x(0|[1-9a-fA-F][\da-fA-F]*)$ 匹配。

CLASS->_from_bytes(STR)

给定表示数字的字节字符串，返回一个对象。字节字符串采用大端字节序，因此二字节输入字符串 "\x01\x00" 应该给出表示数字 256 的输出值。

CLASS->_from_base(STR, BASE, COLLSEQ)

给定字符串 STR、基数 BASE 和排序序列 COLLSEQ，返回一个对象。STR 中的每个字符都代表一个数值，该数值与 COLLSEQ 中字符的位置相同。STR 中的所有字符都必须出现在 COLLSEQ 中。

如果 BASE 小于或等于 94，并且没有指定排序规则，则使用以下默认排序规则。它包含所有 94 个可打印的 ASCII 字符，除了空格/空白。

0123456789                  # ASCII  48 to  57
ABCDEFGHIJKLMNOPQRSTUVWXYZ  # ASCII  65 to  90
abcdefghijklmnopqrstuvwxyz  # ASCII  97 to 122
!"#$%&'()*+,-./             # ASCII  33 to  47
:;<=>?@                     # ASCII  58 to  64
[\]^_`                      # ASCII  91 to  96
{|}~                        # ASCII 123 to 126

如果使用默认排序规则，并且 BASE 小于或等于 36，则忽略 STR 中的字母大小写。

例如，对于基数为 3 且排序规则为 "-/|"，字符 "-" 表示 0，"/" 表示 1，"|" 表示 2。因此，如果 STR 为 "/|-", 则输出为 1 * 3**2 + 2 * 3**1 + 0 * 3**0 = 15。

以下示例显示标准二进制、八进制、十进制和十六进制转换。所有示例都返回 250。

$x = $class -> _from_base("11111010", 2)
$x = $class -> _from_base("372", 8)
$x = $class -> _from_base("250", 10)
$x = $class -> _from_base("FA", 16)

更多示例，都返回 250

$x = $class -> _from_base("100021", 3)
$x = $class -> _from_base("3322", 4)
$x = $class -> _from_base("2000", 5)
$x = $class -> _from_base("caaa", 5, "abcde")
$x = $class -> _from_base("42", 62)
$x = $class -> _from_base("2!", 94)
CLASS->_from_base_num(ARRAY, BASE)

给定一个值数组和一个基数，返回一个对象。此方法等效于 _from_base()，但作用于数组中的数字，而不是字符串中的字符。与 _from_base() 不同，所有输入值都可以任意大。

$x = $class -> _from_base_num([1, 1, 0, 1], 2)    # $x is 13
$x = $class -> _from_base_num([3, 125, 39], 128)  # $x is 65191

数学函数

CLASS->_add(OBJ1, OBJ2)

加法。返回将 OBJ2 加到 OBJ1 的结果。

CLASS->_mul(OBJ1, OBJ2)

乘法。返回将 OBJ2 和 OBJ1 相乘的结果。

CLASS->_div(OBJ1, OBJ2)

除法。在标量上下文中，返回将 OBJ1 除以 OBJ2 并将结果截断为整数后的商。在列表上下文中，返回商和余数。

CLASS->_sub(OBJ1, OBJ2, FLAG)
CLASS->_sub(OBJ1, OBJ2)

减法。返回将 OBJ2 从 OBJ1 中减去的结果。如果 flag 为假或省略，则 OBJ1 可能被修改。如果 flag 为真，则 OBJ2 可能被修改。

CLASS->_sadd(OBJ1, SIGN1, OBJ2, SIGN2)

带符号加法。返回将 OBJ2 与符号 SIGN2 加到 OBJ1 与符号 SIGN1 的结果。

($obj3, $sign3) = $class -> _sadd($obj1, $sign1, $obj2, $sign2);
CLASS->_ssub(OBJ1, SIGN1, OBJ2, SIGN2)

带符号减法。返回将 OBJ2 与符号 SIGN2 从 OBJ1 与符号 SIGN1 中减去的结果。

($obj3, $sign3) = $class -> _sadd($obj1, $sign1, $obj2, $sign2);
CLASS->_dec(OBJ)

返回 OBJ 减 1 后的结果。

CLASS->_inc(OBJ)

返回 OBJ 加 1 后的结果。

CLASS->_mod(OBJ1, OBJ2)

返回 OBJ1 模 OBJ2 的结果，即 OBJ1 除以 OBJ2 后的余数。

CLASS->_sqrt(OBJ)

返回 OBJ 的平方根，截断为整数。

CLASS->_root(OBJ, N)

返回 OBJ 的 N 次方根，截断为整数。

CLASS->_fac(OBJ)

返回 OBJ 的阶乘，即所有正整数从 1 到 OBJ 的乘积。

CLASS->_dfac(OBJ)

返回 OBJ 的双阶乘。如果 OBJ 是偶数，则返回所有正偶数从 2 到 OBJ 的乘积，即 2*4*6*...*OBJ。如果 OBJ 是奇数，则返回所有正奇数从 1 到 OBJ 的乘积，即 1*3*5*...*OBJ。

CLASS->_pow(OBJ1, OBJ2)

返回 OBJ1 的 OBJ2 次方。按照惯例，0**0 = 1。

CLASS->_modinv(OBJ1, OBJ2)

返回模乘逆，即返回 OBJ3 使得

(OBJ3 * OBJ1) % OBJ2 = 1 % OBJ2

结果以两个参数返回。如果模乘逆不存在，则两个参数都未定义。否则，参数是一个数字（对象）及其符号（“+”或“-”）。

输出值及其符号必须是 1,2,...,OBJ2-1 范围内的正值，或者减去 OBJ2 的相同值。例如，如果输入参数是表示数字 7 和 5 的对象，则该方法必须返回表示数字 3 的对象和一个“+”符号，因为 (3*7) % 5 = 1 % 5，或者返回表示数字 2 的对象和一个“-”符号，因为 (-2*7) % 5 = 1 % 5。

CLASS->_modpow(OBJ1, OBJ2, OBJ3)

返回模幂运算，即 (OBJ1 ** OBJ2) % OBJ3。

CLASS->_rsft(OBJ, N, B)

返回将 OBJ 在 B 进制下向右移 N 位的结果。这等效于执行整数除以 B**N 并丢弃余数，但它可能快得多。

例如，如果对象 $obj 表示十六进制数 0xabcde，则 _rsft($obj, 2, 16) 返回表示数字 0xabc 的对象。 “余数” 0xde 被丢弃，不会返回。

CLASS->_lsft(OBJ, N, B)

返回将 OBJ 在 B 进制下左移 N 位后的结果。这等效于乘以 B**N，但可能更快。

CLASS->_log_int(OBJ, B)

返回 OBJ 以 BASE 为底的对数，截断为整数。此方法有两个输出参数，OBJECT 和 STATUS。STATUS 是 Perl 标量；如果 OBJ 是精确结果，则为 1；如果结果被截断以给出 OBJ，则为 0；如果无法确定 OBJ 是否是精确结果，则为 undef。

CLASS->_gcd(OBJ1, OBJ2)

返回 OBJ1 和 OBJ2 的最大公约数。

CLASS->_lcm(OBJ1, OBJ2)

返回 OBJ1 和 OBJ2 的最小公倍数。

CLASS->_fib(OBJ)

在标量上下文中，返回第 n 个斐波那契数：_fib(0) 返回 0，_fib(1) 返回 1，_fib(2) 返回 1，_fib(3) 返回 2 等等。在列表上下文中，返回从 F(0) 到 F(n) 的斐波那契数：0、1、1、2、3、5、8、13、21、34、...

CLASS->_lucas(OBJ)

在标量上下文中，返回第 n 个卢卡斯数：_lucas(0) 返回 2，_lucas(1) 返回 1，_lucas(2) 返回 3，等等。在列表上下文中，返回从 L(0) 到 L(n) 的卢卡斯数：2、1、3、4、7、11、18、29、47、76、...

位运算符

CLASS->_and(OBJ1, OBJ2)

返回按位与。

CLASS->_or(OBJ1, OBJ2)

返回按位或。

CLASS->_xor(OBJ1, OBJ2)

返回按位异或。

CLASS->_sand(OBJ1, OBJ2, SIGN1, SIGN2)

返回按位有符号与。

CLASS->_sor(OBJ1, OBJ2, SIGN1, SIGN2)

返回按位有符号或运算结果。

CLASS->_sxor(OBJ1, OBJ2, SIGN1, SIGN2)

返回按位有符号异或运算结果。

布尔运算符

CLASS->_is_zero(OBJ)

如果 OBJ 为零，则返回真值，否则返回假值。

CLASS->_is_one(OBJ)

如果 OBJ 为一，则返回真值，否则返回假值。

CLASS->_is_two(OBJ)

如果 OBJ 为二，则返回真值，否则返回假值。

CLASS->_is_ten(OBJ)

如果 OBJ 为十，则返回真值，否则返回假值。

CLASS->_is_even(OBJ)

如果 OBJ 是偶数，则返回真值，否则返回假值。

CLASS->_is_odd(OBJ)

如果 OBJ 是偶数，则返回真值，否则返回假值。

CLASS->_acmp(OBJ1, OBJ2)

比较 OBJ1 和 OBJ2，如果 OBJ1 数值小于、等于或大于 OBJ2，分别返回 -1、0 或 1。

字符串转换

CLASS->_str(OBJ)

返回以十进制表示的 OBJ 的字符串。返回的字符串不应有前导零，即应匹配 ^(0|[1-9]\d*)$。

CLASS->_to_bin(OBJ)

返回 OBJ 的二进制字符串表示。

CLASS->_to_oct(OBJ)

返回数字的八进制字符串表示。

CLASS->_to_hex(OBJ)

返回数字的十六进制字符串表示。

CLASS->_to_bytes(OBJ)

返回 OBJ 的字节字符串表示形式。字节字符串采用大端字节序，因此如果 OBJ 表示数字 256，则输出应为两字节字符串“\x01\x00”。

CLASS->_to_base(OBJ, BASE, COLLSEQ)

返回 OBJ 在基数 BASE 中的字符串表示形式，排序规则为 COLLSEQ。

$val = $class -> _new("210");
$str = $class -> _to_base($val, 10, "xyz")  # $str is "zyx"

$val = $class -> _new("32");
$str = $class -> _to_base($val, 2, "-|")  # $str is "|-----"

有关更多信息，请参阅 _from_base()。

CLASS->_to_base_num(OBJ, BASE)

将给定数字转换为给定基数。此方法等效于 _to_base()，但返回数组中的数字而不是字符串中的字符。在输出中，第一个元素是最重要的元素。与 _to_base() 不同，所有输入值都可以任意大。

$x = $class -> _to_base_num(13, 2)        # $x is [1, 1, 0, 1]
$x = $class -> _to_base_num(65191, 128)   # $x is [3, 125, 39]
CLASS->_as_bin(OBJ)

与 _to_bin() 相似，但带有“0b”前缀。

CLASS->_as_oct(OBJ)

与 _to_oct() 相似，但带有“0”前缀。

CLASS->_as_hex(OBJ)

与 _to_hex() 相似，但带有“0x”前缀。

CLASS->_as_bytes(OBJ)

这是 _to_bytes() 的别名。

数字转换

CLASS->_num(OBJ)

返回一个 Perl 标量数字，它尽可能接近地表示数字 OBJ。由于 Perl 标量具有有限的精度，因此返回值可能与 OBJ 不完全相同。

其他

CLASS->_copy(OBJ)

返回 OBJ 的真实副本。

CLASS->_len(OBJ)

返回 OBJ 中十进制数字的个数。输出为 Perl 标量。

CLASS->_zeros(OBJ)

返回尾随十进制零的个数。输出为 Perl 标量。数字零没有尾随十进制零。

CLASS->_digit(OBJ, N)

返回 OBJ 中的第 N 位数字，作为 Perl 标量。N 是一个 Perl 标量，其中零表示最右边的（最低有效）数字，负值表示从左边（最高有效数字）开始计数。如果 $obj 表示数字 123，则

CLASS->_digit($obj,  0)     # returns 3
CLASS->_digit($obj,  1)     # returns 2
CLASS->_digit($obj,  2)     # returns 1
CLASS->_digit($obj, -1)     # returns 1
CLASS->_digitsum(OBJ)

返回基数为 10 的数字之和。

CLASS->_check(OBJ)

如果对象无效则返回 true，否则返回 false。最好，true 值是一个字符串，描述了对象的问题。这是一个检查例程，用于测试对象的内部状态是否已损坏。

CLASS->_set(OBJ)

xxx

API 版本 2

以下方法是 API 版本 2 或更高版本所需的。

构造函数

CLASS->_1ex(N)

返回一个表示数字 10**N 的对象，其中 N >= 0 是一个 Perl 标量。

数学函数

CLASS->_nok(OBJ1, OBJ2)

返回二项式系数 OBJ1 除以 OBJ1。

其他

CLASS->_alen(OBJ)

返回对象的十进制数字的近似值。输出是一个 Perl 标量。

包装您自己的

如果您想将您自己喜欢的 C 库移植到 Math::BigInt 接口，您可以参考任何现有的模块。您应该真正用您的模块包装最新的 Math::BigInt 和 Math::BigFloat 测试套件，并替换以下内容

use Math::BigInt;

为此

use Math::BigInt lib => 'yourlib';

这样，您就可以确保您的库在 Math::BigInt 中 100% 地工作。

错误

请将任何错误或功能请求报告到 bug-math-bigint at rt.cpan.org，或通过网络界面报告到 https://rt.cpan.org/Ticket/Create.html?Queue=Math-BigInt（需要登录）。我们会收到通知，然后您会自动收到有关错误进度的通知，因为我会进行更改。

支持

您可以使用 perldoc 命令找到此模块的文档。

perldoc Math::BigInt::Calc

您也可以在以下位置查找信息

许可证

本程序是自由软件；您可以根据与 Perl 本身相同的条款重新发布和/或修改它。

作者

Peter John Acklam, <[email protected]>

代码和文档基于 Tels <[email protected]> 编写的 Math::BigInt::Calc 模块。

另请参阅

Math::BigInt、Math::BigInt::Calc、Math::BigInt::GMP、Math::BigInt::FastCalc 和 Math::BigInt::Pari。