| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Math::BigInt::Lib 3perl" |
| 58 |
.TH Math::BigInt::Lib 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Math::BigInt::Lib \- virtual parent class for Math::BigInt libraries |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& # In the backend library for Math::BigInt et al. |
| 69 |
\& |
| 70 |
\& package Math::BigInt::MyBackend; |
| 71 |
\& |
| 72 |
\& use Math::BigInt::Lib; |
| 73 |
\& our @ISA = qw< Math::BigInt::Lib >; |
| 74 |
\& |
| 75 |
\& sub _new { ... } |
| 76 |
\& sub _str { ... } |
| 77 |
\& sub _add { ... } |
| 78 |
\& str _sub { ... } |
| 79 |
\& ... |
| 80 |
\& |
| 81 |
\& # In your main program. |
| 82 |
\& |
| 83 |
\& use Math::BigInt lib => \*(AqMyBackend\*(Aq; |
| 84 |
.Ve |
| 85 |
.SH DESCRIPTION |
| 86 |
.IX Header "DESCRIPTION" |
| 87 |
This module provides support for big integer calculations. It is not intended |
| 88 |
to be used directly, but rather as a parent class for backend libraries used by |
| 89 |
Math::BigInt, Math::BigFloat, Math::BigRat, and related modules. |
| 90 |
.PP |
| 91 |
Other backend libraries include Math::BigInt::Calc, Math::BigInt::FastCalc, |
| 92 |
Math::BigInt::GMP, and Math::BigInt::Pari. |
| 93 |
.PP |
| 94 |
In order to allow for multiple big integer libraries, Math::BigInt was |
| 95 |
rewritten to use a plug-in library for core math routines. Any module which |
| 96 |
conforms to the API can be used by Math::BigInt by using this in your program: |
| 97 |
.PP |
| 98 |
.Vb 1 |
| 99 |
\& use Math::BigInt lib => \*(Aqlibname\*(Aq; |
| 100 |
.Ve |
| 101 |
.PP |
| 102 |
\&'libname' is either the long name, like 'Math::BigInt::Pari', or only the short |
| 103 |
version, like 'Pari'. |
| 104 |
.SS "General Notes" |
| 105 |
.IX Subsection "General Notes" |
| 106 |
A library only needs to deal with unsigned big integers. Testing of input |
| 107 |
parameter validity is done by the caller, so there is no need to worry about |
| 108 |
underflow (e.g., in \f(CW_sub()\fR and \f(CW_dec()\fR) or about division by zero (e.g., |
| 109 |
in \f(CW_div()\fR and \f(CW_mod()\fR)) or similar cases. |
| 110 |
.PP |
| 111 |
Some libraries use methods that don't modify their argument, and some libraries |
| 112 |
don't even use objects, but rather unblessed references. Because of this, |
| 113 |
liberary methods are always called as class methods, not instance methods: |
| 114 |
.PP |
| 115 |
.Vb 3 |
| 116 |
\& $x = Class \-> method($x, $y); # like this |
| 117 |
\& $x = $x \-> method($y); # not like this ... |
| 118 |
\& $x \-> method($y); # ... or like this |
| 119 |
.Ve |
| 120 |
.PP |
| 121 |
And with boolean methods |
| 122 |
.PP |
| 123 |
.Vb 2 |
| 124 |
\& $bool = Class \-> method($x, $y); # like this |
| 125 |
\& $bool = $x \-> method($y); # not like this |
| 126 |
.Ve |
| 127 |
.PP |
| 128 |
Return values are always objects, strings, Perl scalars, or true/false for |
| 129 |
comparison routines. |
| 130 |
.PP |
| 131 |
\fIAPI version\fR |
| 132 |
.IX Subsection "API version" |
| 133 |
.IP CLASS\->\fBapi_version()\fR 4 |
| 134 |
.IX Item "CLASS->api_version()" |
| 135 |
This method is no longer used and can be omitted. Methods that are not |
| 136 |
implemented by a subclass will be inherited from this class. |
| 137 |
.PP |
| 138 |
\fIConstructors\fR |
| 139 |
.IX Subsection "Constructors" |
| 140 |
.PP |
| 141 |
The following methods are mandatory: \fB_new()\fR, \fB_str()\fR, \fB_add()\fR, and \fB_sub()\fR. |
| 142 |
However, computations will be very slow without \fB_mul()\fR and \fB_div()\fR. |
| 143 |
.IP CLASS\->_new(STR) 4 |
| 144 |
.IX Item "CLASS->_new(STR)" |
| 145 |
Convert a string representing an unsigned decimal number to an object |
| 146 |
representing the same number. The input is normalized, i.e., it matches |
| 147 |
\&\f(CW\*(C`^(0|[1\-9]\ed*)$\*(C'\fR. |
| 148 |
.IP CLASS\->\fB_zero()\fR 4 |
| 149 |
.IX Item "CLASS->_zero()" |
| 150 |
Return an object representing the number zero. |
| 151 |
.IP CLASS\->\fB_one()\fR 4 |
| 152 |
.IX Item "CLASS->_one()" |
| 153 |
Return an object representing the number one. |
| 154 |
.IP CLASS\->\fB_two()\fR 4 |
| 155 |
.IX Item "CLASS->_two()" |
| 156 |
Return an object representing the number two. |
| 157 |
.IP CLASS\->\fB_ten()\fR 4 |
| 158 |
.IX Item "CLASS->_ten()" |
| 159 |
Return an object representing the number ten. |
| 160 |
.IP CLASS\->_from_bin(STR) 4 |
| 161 |
.IX Item "CLASS->_from_bin(STR)" |
| 162 |
Return an object given a string representing a binary number. The input has a |
| 163 |
\&'0b' prefix and matches the regular expression \f(CW\*(C`^0[bB](0|1[01]*)$\*(C'\fR. |
| 164 |
.IP CLASS\->_from_oct(STR) 4 |
| 165 |
.IX Item "CLASS->_from_oct(STR)" |
| 166 |
Return an object given a string representing an octal number. The input has a |
| 167 |
\&'0' prefix and matches the regular expression \f(CW\*(C`^0[1\-7]*$\*(C'\fR. |
| 168 |
.IP CLASS\->_from_hex(STR) 4 |
| 169 |
.IX Item "CLASS->_from_hex(STR)" |
| 170 |
Return an object given a string representing a hexadecimal number. The input |
| 171 |
has a '0x' prefix and matches the regular expression |
| 172 |
\&\f(CW\*(C`^0x(0|[1\-9a\-fA\-F][\eda\-fA\-F]*)$\*(C'\fR. |
| 173 |
.IP CLASS\->_from_bytes(STR) 4 |
| 174 |
.IX Item "CLASS->_from_bytes(STR)" |
| 175 |
Returns an object given a byte string representing the number. The byte string |
| 176 |
is in big endian byte order, so the two-byte input string "\ex01\ex00" should |
| 177 |
give an output value representing the number 256. |
| 178 |
.IP "CLASS\->_from_base(STR, BASE, COLLSEQ)" 4 |
| 179 |
.IX Item "CLASS->_from_base(STR, BASE, COLLSEQ)" |
| 180 |
Returns an object given a string STR, a base BASE, and a collation sequence |
| 181 |
COLLSEQ. Each character in STR represents a numerical value identical to the |
| 182 |
character's position in COLLSEQ. All characters in STR must be present in |
| 183 |
COLLSEQ. |
| 184 |
.Sp |
| 185 |
If BASE is less than or equal to 94, and a collation sequence is not specified, |
| 186 |
the following default collation sequence is used. It contains of all the 94 |
| 187 |
printable ASCII characters except space/blank: |
| 188 |
.Sp |
| 189 |
.Vb 7 |
| 190 |
\& 0123456789 # ASCII 48 to 57 |
| 191 |
\& ABCDEFGHIJKLMNOPQRSTUVWXYZ # ASCII 65 to 90 |
| 192 |
\& abcdefghijklmnopqrstuvwxyz # ASCII 97 to 122 |
| 193 |
\& !"#$%&\*(Aq()*+,\-./ # ASCII 33 to 47 |
| 194 |
\& :;<=>?@ # ASCII 58 to 64 |
| 195 |
\& [\e]^_\` # ASCII 91 to 96 |
| 196 |
\& {|}~ # ASCII 123 to 126 |
| 197 |
.Ve |
| 198 |
.Sp |
| 199 |
If the default collation sequence is used, and the BASE is less than or equal |
| 200 |
to 36, the letter case in STR is ignored. |
| 201 |
.Sp |
| 202 |
For instance, with base 3 and collation sequence "\-/|", the character "\-" |
| 203 |
represents 0, "/" represents 1, and "|" represents 2. So if STR is "/|\-", the |
| 204 |
output is 1 * 3**2 + 2 * 3**1 + 0 * 3**0 = 15. |
| 205 |
.Sp |
| 206 |
The following examples show standard binary, octal, decimal, and hexadecimal |
| 207 |
conversion. All examples return 250. |
| 208 |
.Sp |
| 209 |
.Vb 4 |
| 210 |
\& $x = $class \-> _from_base("11111010", 2) |
| 211 |
\& $x = $class \-> _from_base("372", 8) |
| 212 |
\& $x = $class \-> _from_base("250", 10) |
| 213 |
\& $x = $class \-> _from_base("FA", 16) |
| 214 |
.Ve |
| 215 |
.Sp |
| 216 |
Some more examples, all returning 250: |
| 217 |
.Sp |
| 218 |
.Vb 6 |
| 219 |
\& $x = $class \-> _from_base("100021", 3) |
| 220 |
\& $x = $class \-> _from_base("3322", 4) |
| 221 |
\& $x = $class \-> _from_base("2000", 5) |
| 222 |
\& $x = $class \-> _from_base("caaa", 5, "abcde") |
| 223 |
\& $x = $class \-> _from_base("42", 62) |
| 224 |
\& $x = $class \-> _from_base("2!", 94) |
| 225 |
.Ve |
| 226 |
.IP "CLASS\->_from_base_num(ARRAY, BASE)" 4 |
| 227 |
.IX Item "CLASS->_from_base_num(ARRAY, BASE)" |
| 228 |
Returns an object given an array of values and a base. This method is |
| 229 |
equivalent to \f(CW_from_base()\fR, but works on numbers in an array rather than |
| 230 |
characters in a string. Unlike \f(CW_from_base()\fR, all input values may be |
| 231 |
arbitrarily large. |
| 232 |
.Sp |
| 233 |
.Vb 2 |
| 234 |
\& $x = $class \-> _from_base_num([1, 1, 0, 1], 2) # $x is 13 |
| 235 |
\& $x = $class \-> _from_base_num([3, 125, 39], 128) # $x is 65191 |
| 236 |
.Ve |
| 237 |
.PP |
| 238 |
\fIMathematical functions\fR |
| 239 |
.IX Subsection "Mathematical functions" |
| 240 |
.IP "CLASS\->_add(OBJ1, OBJ2)" 4 |
| 241 |
.IX Item "CLASS->_add(OBJ1, OBJ2)" |
| 242 |
Addition. Returns the result of adding OBJ2 to OBJ1. |
| 243 |
.IP "CLASS\->_mul(OBJ1, OBJ2)" 4 |
| 244 |
.IX Item "CLASS->_mul(OBJ1, OBJ2)" |
| 245 |
Multiplication. Returns the result of multiplying OBJ2 and OBJ1. |
| 246 |
.IP "CLASS\->_div(OBJ1, OBJ2)" 4 |
| 247 |
.IX Item "CLASS->_div(OBJ1, OBJ2)" |
| 248 |
Division. In scalar context, returns the quotient after dividing OBJ1 by OBJ2 |
| 249 |
and truncating the result to an integer. In list context, return the quotient |
| 250 |
and the remainder. |
| 251 |
.IP "CLASS\->_sub(OBJ1, OBJ2, FLAG)" 4 |
| 252 |
.IX Item "CLASS->_sub(OBJ1, OBJ2, FLAG)" |
| 253 |
.PD 0 |
| 254 |
.IP "CLASS\->_sub(OBJ1, OBJ2)" 4 |
| 255 |
.IX Item "CLASS->_sub(OBJ1, OBJ2)" |
| 256 |
.PD |
| 257 |
Subtraction. Returns the result of subtracting OBJ2 by OBJ1. If \f(CW\*(C`flag\*(C'\fR is false |
| 258 |
or omitted, OBJ1 might be modified. If \f(CW\*(C`flag\*(C'\fR is true, OBJ2 might be modified. |
| 259 |
.IP "CLASS\->_sadd(OBJ1, SIGN1, OBJ2, SIGN2)" 4 |
| 260 |
.IX Item "CLASS->_sadd(OBJ1, SIGN1, OBJ2, SIGN2)" |
| 261 |
Signed addition. Returns the result of adding OBJ2 with sign SIGN2 to OBJ1 with |
| 262 |
sign SIGN1. |
| 263 |
.Sp |
| 264 |
.Vb 1 |
| 265 |
\& ($obj3, $sign3) = $class \-> _sadd($obj1, $sign1, $obj2, $sign2); |
| 266 |
.Ve |
| 267 |
.IP "CLASS\->_ssub(OBJ1, SIGN1, OBJ2, SIGN2)" 4 |
| 268 |
.IX Item "CLASS->_ssub(OBJ1, SIGN1, OBJ2, SIGN2)" |
| 269 |
Signed subtraction. Returns the result of subtracting OBJ2 with sign SIGN2 to |
| 270 |
OBJ1 with sign SIGN1. |
| 271 |
.Sp |
| 272 |
.Vb 1 |
| 273 |
\& ($obj3, $sign3) = $class \-> _sadd($obj1, $sign1, $obj2, $sign2); |
| 274 |
.Ve |
| 275 |
.IP CLASS\->_dec(OBJ) 4 |
| 276 |
.IX Item "CLASS->_dec(OBJ)" |
| 277 |
Returns the result after decrementing OBJ by one. |
| 278 |
.IP CLASS\->_inc(OBJ) 4 |
| 279 |
.IX Item "CLASS->_inc(OBJ)" |
| 280 |
Returns the result after incrementing OBJ by one. |
| 281 |
.IP "CLASS\->_mod(OBJ1, OBJ2)" 4 |
| 282 |
.IX Item "CLASS->_mod(OBJ1, OBJ2)" |
| 283 |
Returns OBJ1 modulo OBJ2, i.e., the remainder after dividing OBJ1 by OBJ2. |
| 284 |
.IP CLASS\->_sqrt(OBJ) 4 |
| 285 |
.IX Item "CLASS->_sqrt(OBJ)" |
| 286 |
Returns the square root of OBJ, truncated to an integer. |
| 287 |
.IP "CLASS\->_root(OBJ, N)" 4 |
| 288 |
.IX Item "CLASS->_root(OBJ, N)" |
| 289 |
Returns the Nth root of OBJ, truncated to an integer. |
| 290 |
.IP CLASS\->_fac(OBJ) 4 |
| 291 |
.IX Item "CLASS->_fac(OBJ)" |
| 292 |
Returns the factorial of OBJ, i.e., the product of all positive integers up to |
| 293 |
and including OBJ. |
| 294 |
.IP CLASS\->_dfac(OBJ) 4 |
| 295 |
.IX Item "CLASS->_dfac(OBJ)" |
| 296 |
Returns the double factorial of OBJ. If OBJ is an even integer, returns the |
| 297 |
product of all positive, even integers up to and including OBJ, i.e., |
| 298 |
2*4*6*...*OBJ. If OBJ is an odd integer, returns the product of all positive, |
| 299 |
odd integers, i.e., 1*3*5*...*OBJ. |
| 300 |
.IP "CLASS\->_pow(OBJ1, OBJ2)" 4 |
| 301 |
.IX Item "CLASS->_pow(OBJ1, OBJ2)" |
| 302 |
Returns OBJ1 raised to the power of OBJ2. By convention, 0**0 = 1. |
| 303 |
.IP "CLASS\->_modinv(OBJ1, OBJ2)" 4 |
| 304 |
.IX Item "CLASS->_modinv(OBJ1, OBJ2)" |
| 305 |
Returns the modular multiplicative inverse, i.e., return OBJ3 so that |
| 306 |
.Sp |
| 307 |
.Vb 1 |
| 308 |
\& (OBJ3 * OBJ1) % OBJ2 = 1 % OBJ2 |
| 309 |
.Ve |
| 310 |
.Sp |
| 311 |
The result is returned as two arguments. If the modular multiplicative inverse |
| 312 |
does not exist, both arguments are undefined. Otherwise, the arguments are a |
| 313 |
number (object) and its sign ("+" or "\-"). |
| 314 |
.Sp |
| 315 |
The output value, with its sign, must either be a positive value in the range |
| 316 |
1,2,...,OBJ2\-1 or the same value subtracted OBJ2. For instance, if the input |
| 317 |
arguments are objects representing the numbers 7 and 5, the method must either |
| 318 |
return an object representing the number 3 and a "+" sign, since (3*7) % 5 = 1 |
| 319 |
% 5, or an object representing the number 2 and a "\-" sign, since (\-2*7) % 5 = 1 |
| 320 |
% 5. |
| 321 |
.IP "CLASS\->_modpow(OBJ1, OBJ2, OBJ3)" 4 |
| 322 |
.IX Item "CLASS->_modpow(OBJ1, OBJ2, OBJ3)" |
| 323 |
Returns the modular exponentiation, i.e., (OBJ1 ** OBJ2) % OBJ3. |
| 324 |
.IP "CLASS\->_rsft(OBJ, N, B)" 4 |
| 325 |
.IX Item "CLASS->_rsft(OBJ, N, B)" |
| 326 |
Returns the result after shifting OBJ N digits to thee right in base B. This is |
| 327 |
equivalent to performing integer division by B**N and discarding the remainder, |
| 328 |
except that it might be much faster. |
| 329 |
.Sp |
| 330 |
For instance, if the object \f(CW$obj\fR represents the hexadecimal number 0xabcde, |
| 331 |
then \f(CW\*(C`_rsft($obj, 2, 16)\*(C'\fR returns an object representing the number 0xabc. The |
| 332 |
"remainer", 0xde, is discarded and not returned. |
| 333 |
.IP "CLASS\->_lsft(OBJ, N, B)" 4 |
| 334 |
.IX Item "CLASS->_lsft(OBJ, N, B)" |
| 335 |
Returns the result after shifting OBJ N digits to the left in base B. This is |
| 336 |
equivalent to multiplying by B**N, except that it might be much faster. |
| 337 |
.IP "CLASS\->_log_int(OBJ, B)" 4 |
| 338 |
.IX Item "CLASS->_log_int(OBJ, B)" |
| 339 |
Returns the logarithm of OBJ to base BASE truncted to an integer. This method |
| 340 |
has two output arguments, the OBJECT and a STATUS. The STATUS is Perl scalar; |
| 341 |
it is 1 if OBJ is the exact result, 0 if the result was truncted to give OBJ, |
| 342 |
and undef if it is unknown whether OBJ is the exact result. |
| 343 |
.IP CLASS\->_ilog2(OBJ) 4 |
| 344 |
.IX Item "CLASS->_ilog2(OBJ)" |
| 345 |
Returns the base 2 logarithm of OBJ rounded downwards to the nearest integer, |
| 346 |
i.e., \f(CW\*(C`int(log2(OBJ))\*(C'\fR. In list context, this method returns two output |
| 347 |
arguments, the OBJECT and a STATUS. The STATUS is Perl scalar; it is 1 if OBJ |
| 348 |
is the exact result, 0 if the result was truncted to give OBJ, and undef if it |
| 349 |
is unknown whether OBJ is the exact result. |
| 350 |
.Sp |
| 351 |
This method is equivalent to the more general method \fB_log_int()\fR when it is used |
| 352 |
with base 2 argument, but \fB_ilog2()\fR method might be faster. |
| 353 |
.IP CLASS\->_ilog10(OBJ) 4 |
| 354 |
.IX Item "CLASS->_ilog10(OBJ)" |
| 355 |
Returns the base 10 logarithm of OBJ rounded downwards to the nearest integer, |
| 356 |
i.e., \f(CW\*(C`int(log2(OBJ))\*(C'\fR. In list context, this method returns two output |
| 357 |
arguments, the OBJECT and a STATUS. The STATUS is Perl scalar; it is 1 if OBJ |
| 358 |
is the exact result, 0 if the result was truncted to give OBJ, and undef if it |
| 359 |
is unknown whether OBJ is the exact result. |
| 360 |
.Sp |
| 361 |
This method is equivalent to the more general method \fB_log_int()\fR when it is used |
| 362 |
with base 10 argument, but \fB_ilog10()\fR method might be faster. |
| 363 |
.Sp |
| 364 |
Also, the output from \fB_ilog10()\fR is always 1 smaller than the output from |
| 365 |
\&\fB_len()\fR. |
| 366 |
.IP CLASS\->_clog2(OBJ) 4 |
| 367 |
.IX Item "CLASS->_clog2(OBJ)" |
| 368 |
Returns the base 2 logarithm of OBJ rounded upwards to the nearest integer, |
| 369 |
i.e., \f(CW\*(C`ceil(log2(OBJ))\*(C'\fR. In list context, this method returns two output |
| 370 |
arguments, the OBJECT and a STATUS. The STATUS is Perl scalar; it is 1 if OBJ |
| 371 |
is the exact result, 0 if the result was truncted to give OBJ, and undef if it |
| 372 |
is unknown whether OBJ is the exact result. |
| 373 |
.IP CLASS\->_clog10(OBJ) 4 |
| 374 |
.IX Item "CLASS->_clog10(OBJ)" |
| 375 |
Returns the base 10 logarithm of OBJ rounded upnwards to the nearest integer, |
| 376 |
i.e., \f(CW\*(C`ceil(log2(OBJ))\*(C'\fR. In list context, this method returns two output |
| 377 |
arguments, the OBJECT and a STATUS. The STATUS is Perl scalar; it is 1 if OBJ |
| 378 |
is the exact result, 0 if the result was truncted to give OBJ, and undef if it |
| 379 |
is unknown whether OBJ is the exact result. |
| 380 |
.IP "CLASS\->_gcd(OBJ1, OBJ2)" 4 |
| 381 |
.IX Item "CLASS->_gcd(OBJ1, OBJ2)" |
| 382 |
Returns the greatest common divisor of OBJ1 and OBJ2. |
| 383 |
.IP "CLASS\->_lcm(OBJ1, OBJ2)" 4 |
| 384 |
.IX Item "CLASS->_lcm(OBJ1, OBJ2)" |
| 385 |
Return the least common multiple of OBJ1 and OBJ2. |
| 386 |
.IP CLASS\->_fib(OBJ) 4 |
| 387 |
.IX Item "CLASS->_fib(OBJ)" |
| 388 |
In scalar context, returns the nth Fibonacci number: \fB_fib\fR\|(0) returns 0, \fB_fib\fR\|(1) |
| 389 |
returns 1, \fB_fib\fR\|(2) returns 1, \fB_fib\fR\|(3) returns 2 etc. In list context, returns |
| 390 |
the Fibonacci numbers from F(0) to F(n): 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, ... |
| 391 |
.IP CLASS\->_lucas(OBJ) 4 |
| 392 |
.IX Item "CLASS->_lucas(OBJ)" |
| 393 |
In scalar context, returns the nth Lucas number: \fB_lucas\fR\|(0) returns 2, \fB_lucas\fR\|(1) |
| 394 |
returns 1, \fB_lucas\fR\|(2) returns 3, etc. In list context, returns the Lucas numbers |
| 395 |
from L(0) to L(n): 2, 1, 3, 4, 7, 11, 18, 29,47, 76, ... |
| 396 |
.PP |
| 397 |
\fIBitwise operators\fR |
| 398 |
.IX Subsection "Bitwise operators" |
| 399 |
.IP "CLASS\->_and(OBJ1, OBJ2)" 4 |
| 400 |
.IX Item "CLASS->_and(OBJ1, OBJ2)" |
| 401 |
Returns bitwise and. |
| 402 |
.IP "CLASS\->_or(OBJ1, OBJ2)" 4 |
| 403 |
.IX Item "CLASS->_or(OBJ1, OBJ2)" |
| 404 |
Returns bitwise or. |
| 405 |
.IP "CLASS\->_xor(OBJ1, OBJ2)" 4 |
| 406 |
.IX Item "CLASS->_xor(OBJ1, OBJ2)" |
| 407 |
Returns bitwise exclusive or. |
| 408 |
.IP "CLASS\->_sand(OBJ1, OBJ2, SIGN1, SIGN2)" 4 |
| 409 |
.IX Item "CLASS->_sand(OBJ1, OBJ2, SIGN1, SIGN2)" |
| 410 |
Returns bitwise signed and. |
| 411 |
.IP "CLASS\->_sor(OBJ1, OBJ2, SIGN1, SIGN2)" 4 |
| 412 |
.IX Item "CLASS->_sor(OBJ1, OBJ2, SIGN1, SIGN2)" |
| 413 |
Returns bitwise signed or. |
| 414 |
.IP "CLASS\->_sxor(OBJ1, OBJ2, SIGN1, SIGN2)" 4 |
| 415 |
.IX Item "CLASS->_sxor(OBJ1, OBJ2, SIGN1, SIGN2)" |
| 416 |
Returns bitwise signed exclusive or. |
| 417 |
.PP |
| 418 |
\fIBoolean operators\fR |
| 419 |
.IX Subsection "Boolean operators" |
| 420 |
.IP CLASS\->_is_zero(OBJ) 4 |
| 421 |
.IX Item "CLASS->_is_zero(OBJ)" |
| 422 |
Returns a true value if OBJ is zero, and false value otherwise. |
| 423 |
.IP CLASS\->_is_one(OBJ) 4 |
| 424 |
.IX Item "CLASS->_is_one(OBJ)" |
| 425 |
Returns a true value if OBJ is one, and false value otherwise. |
| 426 |
.IP CLASS\->_is_two(OBJ) 4 |
| 427 |
.IX Item "CLASS->_is_two(OBJ)" |
| 428 |
Returns a true value if OBJ is two, and false value otherwise. |
| 429 |
.IP CLASS\->_is_ten(OBJ) 4 |
| 430 |
.IX Item "CLASS->_is_ten(OBJ)" |
| 431 |
Returns a true value if OBJ is ten, and false value otherwise. |
| 432 |
.IP CLASS\->_is_even(OBJ) 4 |
| 433 |
.IX Item "CLASS->_is_even(OBJ)" |
| 434 |
Return a true value if OBJ is an even integer, and a false value otherwise. |
| 435 |
.IP CLASS\->_is_odd(OBJ) 4 |
| 436 |
.IX Item "CLASS->_is_odd(OBJ)" |
| 437 |
Return a true value if OBJ is an even integer, and a false value otherwise. |
| 438 |
.IP "CLASS\->_acmp(OBJ1, OBJ2)" 4 |
| 439 |
.IX Item "CLASS->_acmp(OBJ1, OBJ2)" |
| 440 |
Compare OBJ1 and OBJ2 and return \-1, 0, or 1, if OBJ1 is numerically less than, |
| 441 |
equal to, or larger than OBJ2, respectively. |
| 442 |
.PP |
| 443 |
\fIString conversion\fR |
| 444 |
.IX Subsection "String conversion" |
| 445 |
.IP CLASS\->_str(OBJ) 4 |
| 446 |
.IX Item "CLASS->_str(OBJ)" |
| 447 |
Returns a string representing OBJ in decimal notation. The returned string |
| 448 |
should have no leading zeros, i.e., it should match \f(CW\*(C`^(0|[1\-9]\ed*)$\*(C'\fR. |
| 449 |
.IP CLASS\->_to_bin(OBJ) 4 |
| 450 |
.IX Item "CLASS->_to_bin(OBJ)" |
| 451 |
Returns the binary string representation of OBJ. |
| 452 |
.IP CLASS\->_to_oct(OBJ) 4 |
| 453 |
.IX Item "CLASS->_to_oct(OBJ)" |
| 454 |
Returns the octal string representation of the number. |
| 455 |
.IP CLASS\->_to_hex(OBJ) 4 |
| 456 |
.IX Item "CLASS->_to_hex(OBJ)" |
| 457 |
Returns the hexadecimal string representation of the number. |
| 458 |
.IP CLASS\->_to_bytes(OBJ) 4 |
| 459 |
.IX Item "CLASS->_to_bytes(OBJ)" |
| 460 |
Returns a byte string representation of OBJ. The byte string is in big endian |
| 461 |
byte order, so if OBJ represents the number 256, the output should be the |
| 462 |
two-byte string "\ex01\ex00". |
| 463 |
.IP "CLASS\->_to_base(OBJ, BASE, COLLSEQ)" 4 |
| 464 |
.IX Item "CLASS->_to_base(OBJ, BASE, COLLSEQ)" |
| 465 |
Returns a string representation of OBJ in base BASE with collation sequence |
| 466 |
COLLSEQ. |
| 467 |
.Sp |
| 468 |
.Vb 2 |
| 469 |
\& $val = $class \-> _new("210"); |
| 470 |
\& $str = $class \-> _to_base($val, 10, "xyz") # $str is "zyx" |
| 471 |
\& |
| 472 |
\& $val = $class \-> _new("32"); |
| 473 |
\& $str = $class \-> _to_base($val, 2, "\-|") # $str is "|\-\-\-\-\-" |
| 474 |
.Ve |
| 475 |
.Sp |
| 476 |
See \fB_from_base()\fR for more information. |
| 477 |
.IP "CLASS\->_to_base_num(OBJ, BASE)" 4 |
| 478 |
.IX Item "CLASS->_to_base_num(OBJ, BASE)" |
| 479 |
Converts the given number to the given base. This method is equivalent to |
| 480 |
\&\f(CW_to_base()\fR, but returns numbers in an array rather than characters in a |
| 481 |
string. In the output, the first element is the most significant. Unlike |
| 482 |
\&\f(CW_to_base()\fR, all input values may be arbitrarily large. |
| 483 |
.Sp |
| 484 |
.Vb 2 |
| 485 |
\& $x = $class \-> _to_base_num(13, 2) # $x is [1, 1, 0, 1] |
| 486 |
\& $x = $class \-> _to_base_num(65191, 128) # $x is [3, 125, 39] |
| 487 |
.Ve |
| 488 |
.IP CLASS\->_as_bin(OBJ) 4 |
| 489 |
.IX Item "CLASS->_as_bin(OBJ)" |
| 490 |
Like \f(CW_to_bin()\fR but with a '0b' prefix. |
| 491 |
.IP CLASS\->_as_oct(OBJ) 4 |
| 492 |
.IX Item "CLASS->_as_oct(OBJ)" |
| 493 |
Like \f(CW_to_oct()\fR but with a '0' prefix. |
| 494 |
.IP CLASS\->_as_hex(OBJ) 4 |
| 495 |
.IX Item "CLASS->_as_hex(OBJ)" |
| 496 |
Like \f(CW_to_hex()\fR but with a '0x' prefix. |
| 497 |
.IP CLASS\->_as_bytes(OBJ) 4 |
| 498 |
.IX Item "CLASS->_as_bytes(OBJ)" |
| 499 |
This is an alias to \f(CW_to_bytes()\fR. |
| 500 |
.PP |
| 501 |
\fINumeric conversion\fR |
| 502 |
.IX Subsection "Numeric conversion" |
| 503 |
.IP CLASS\->_num(OBJ) 4 |
| 504 |
.IX Item "CLASS->_num(OBJ)" |
| 505 |
Returns a Perl scalar number representing the number OBJ as close as |
| 506 |
possible. Since Perl scalars have limited precision, the returned value might |
| 507 |
not be exactly the same as OBJ. |
| 508 |
.PP |
| 509 |
\fIMiscellaneous\fR |
| 510 |
.IX Subsection "Miscellaneous" |
| 511 |
.IP CLASS\->_copy(OBJ) 4 |
| 512 |
.IX Item "CLASS->_copy(OBJ)" |
| 513 |
Returns a true copy OBJ. |
| 514 |
.IP CLASS\->_len(OBJ) 4 |
| 515 |
.IX Item "CLASS->_len(OBJ)" |
| 516 |
Returns the number of the decimal digits in OBJ. The output is a Perl scalar. |
| 517 |
.IP CLASS\->_zeros(OBJ) 4 |
| 518 |
.IX Item "CLASS->_zeros(OBJ)" |
| 519 |
Returns the number of trailing decimal zeros. The output is a Perl scalar. The |
| 520 |
number zero has no trailing decimal zeros. |
| 521 |
.IP "CLASS\->_digit(OBJ, N)" 4 |
| 522 |
.IX Item "CLASS->_digit(OBJ, N)" |
| 523 |
Returns the Nth digit in OBJ as a Perl scalar. N is a Perl scalar, where zero |
| 524 |
refers to the rightmost (least significant) digit, and negative values count |
| 525 |
from the left (most significant digit). If \f(CW$obj\fR represents the number 123, then |
| 526 |
.Sp |
| 527 |
.Vb 4 |
| 528 |
\& CLASS\->_digit($obj, 0) # returns 3 |
| 529 |
\& CLASS\->_digit($obj, 1) # returns 2 |
| 530 |
\& CLASS\->_digit($obj, 2) # returns 1 |
| 531 |
\& CLASS\->_digit($obj, \-1) # returns 1 |
| 532 |
.Ve |
| 533 |
.IP CLASS\->_digitsum(OBJ) 4 |
| 534 |
.IX Item "CLASS->_digitsum(OBJ)" |
| 535 |
Returns the sum of the base 10 digits. |
| 536 |
.IP CLASS\->_check(OBJ) 4 |
| 537 |
.IX Item "CLASS->_check(OBJ)" |
| 538 |
Returns true if the object is invalid and false otherwise. Preferably, the true |
| 539 |
value is a string describing the problem with the object. This is a check |
| 540 |
routine to test the internal state of the object for corruption. |
| 541 |
.IP CLASS\->_set(OBJ) 4 |
| 542 |
.IX Item "CLASS->_set(OBJ)" |
| 543 |
xxx |
| 544 |
.SS "API version 2" |
| 545 |
.IX Subsection "API version 2" |
| 546 |
The following methods are required for an API version of 2 or greater. |
| 547 |
.PP |
| 548 |
\fIConstructors\fR |
| 549 |
.IX Subsection "Constructors" |
| 550 |
.IP CLASS\->_1ex(N) 4 |
| 551 |
.IX Item "CLASS->_1ex(N)" |
| 552 |
Return an object representing the number 10**N where N >= 0 is a Perl |
| 553 |
scalar. |
| 554 |
.PP |
| 555 |
\fIMathematical functions\fR |
| 556 |
.IX Subsection "Mathematical functions" |
| 557 |
.IP "CLASS\->_nok(OBJ1, OBJ2)" 4 |
| 558 |
.IX Item "CLASS->_nok(OBJ1, OBJ2)" |
| 559 |
Return the binomial coefficient OBJ1 over OBJ1. |
| 560 |
.PP |
| 561 |
\fIMiscellaneous\fR |
| 562 |
.IX Subsection "Miscellaneous" |
| 563 |
.IP CLASS\->_alen(OBJ) 4 |
| 564 |
.IX Item "CLASS->_alen(OBJ)" |
| 565 |
Return the approximate number of decimal digits of the object. The output is a |
| 566 |
Perl scalar. |
| 567 |
.SH "WRAP YOUR OWN" |
| 568 |
.IX Header "WRAP YOUR OWN" |
| 569 |
If you want to port your own favourite C library for big numbers to the |
| 570 |
Math::BigInt interface, you can take any of the already existing modules as a |
| 571 |
rough guideline. You should really wrap up the latest Math::BigInt and |
| 572 |
Math::BigFloat testsuites with your module, and replace in them any of the |
| 573 |
following: |
| 574 |
.PP |
| 575 |
.Vb 1 |
| 576 |
\& use Math::BigInt; |
| 577 |
.Ve |
| 578 |
.PP |
| 579 |
by this: |
| 580 |
.PP |
| 581 |
.Vb 1 |
| 582 |
\& use Math::BigInt lib => \*(Aqyourlib\*(Aq; |
| 583 |
.Ve |
| 584 |
.PP |
| 585 |
This way you ensure that your library really works 100% within Math::BigInt. |
| 586 |
.SH BUGS |
| 587 |
.IX Header "BUGS" |
| 588 |
Please report any bugs or feature requests to |
| 589 |
\&\f(CW\*(C`bug\-math\-bigint at rt.cpan.org\*(C'\fR, or through the web interface at |
| 590 |
<https://rt.cpan.org/Ticket/Create.html?Queue=Math\-BigInt> |
| 591 |
(requires login). |
| 592 |
We will be notified, and then you'll automatically be notified of progress on |
| 593 |
your bug as I make changes. |
| 594 |
.SH SUPPORT |
| 595 |
.IX Header "SUPPORT" |
| 596 |
You can find documentation for this module with the perldoc command. |
| 597 |
.PP |
| 598 |
.Vb 1 |
| 599 |
\& perldoc Math::BigInt::Calc |
| 600 |
.Ve |
| 601 |
.PP |
| 602 |
You can also look for information at: |
| 603 |
.IP \(bu 4 |
| 604 |
GitHub Source Repository |
| 605 |
.Sp |
| 606 |
<https://github.com/pjacklam/p5\-Math\-BigInt> |
| 607 |
.IP \(bu 4 |
| 608 |
RT: CPAN's request tracker |
| 609 |
.Sp |
| 610 |
<https://rt.cpan.org/Public/Dist/Display.html?Name=Math\-BigInt> |
| 611 |
.IP \(bu 4 |
| 612 |
MetaCPAN |
| 613 |
.Sp |
| 614 |
<https://metacpan.org/release/Math\-BigInt> |
| 615 |
.IP \(bu 4 |
| 616 |
CPAN Testers Matrix |
| 617 |
.Sp |
| 618 |
<http://matrix.cpantesters.org/?dist=Math\-BigInt> |
| 619 |
.SH LICENSE |
| 620 |
.IX Header "LICENSE" |
| 621 |
This program is free software; you may redistribute it and/or modify it under |
| 622 |
the same terms as Perl itself. |
| 623 |
.SH AUTHOR |
| 624 |
.IX Header "AUTHOR" |
| 625 |
Peter John Acklam, <[email protected]> |
| 626 |
.PP |
| 627 |
Code and documentation based on the Math::BigInt::Calc module by Tels |
| 628 |
<nospam\[email protected]> |
| 629 |
.SH "SEE ALSO" |
| 630 |
.IX Header "SEE ALSO" |
| 631 |
Math::BigInt, Math::BigInt::Calc, Math::BigInt::GMP, |
| 632 |
Math::BigInt::FastCalc and Math::BigInt::Pari. |