1Math::BigInt::Lib(3) User Contributed Perl Documentation Math::BigInt::Lib(3)
2
6 Math::BigInt::Lib - virtual parent class for Math::BigInt libraries
7
9 # In the backend library for Math::BigInt et al.
10 package Math::BigInt::MyBackend;
12 use Math::BigInt::Lib;
14 our @ISA = qw< Math::BigInt::Lib >;
15 sub _new { ... }
17 sub _str { ... }
18 sub _add { ... }
19 str _sub { ... }
20 ...
21 # In your main program.
23 use Math::BigInt lib => 'MyBackend';
25
27 This module provides support for big integer calculations. It is not
28 intended to be used directly, but rather as a parent class for backend
29 libraries used by Math::BigInt, Math::BigFloat, Math::BigRat, and
30 related modules.
31 Other backend libraries include Math::BigInt::Calc,
33 Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
34 In order to allow for multiple big integer libraries, Math::BigInt was
36 rewritten to use a plug-in library for core math routines. Any module
37 which conforms to the API can be used by Math::BigInt by using this in
38 your program:
39 use Math::BigInt lib => 'libname';
41 'libname' is either the long name, like 'Math::BigInt::Pari', or only
43 the short version, like 'Pari'.
44 General Notes
46 A library only needs to deal with unsigned big integers. Testing of
47 input parameter validity is done by the caller, so there is no need to
48 worry about underflow (e.g., in _sub() and _dec()) or about division by
49 zero (e.g., in _div() and _mod())) or similar cases.
50 Some libraries use methods that don't modify their argument, and some
52 libraries don't even use objects, but rather unblessed references.
53 Because of this, liberary methods are always called as class methods,
54 not instance methods:
55 $x = Class -> method($x, $y); # like this
57 $x = $x -> method($y); # not like this ...
58 $x -> method($y); # ... or like this
59 And with boolean methods
61 $bool = Class -> method($x, $y); # like this
63 $bool = $x -> method($y); # not like this
64 Return values are always objects, strings, Perl scalars, or true/false
66 for comparison routines.
67 API version
69 CLASS->api_version()
71 This method is no longer used and can be omitted. Methods that are
72 not implemented by a subclass will be inherited from this class.
73 Constructors
75 The following methods are mandatory: _new(), _str(), _add(), and
77 _sub(). However, computations will be very slow without _mul() and
78 _div().
79 CLASS->_new(STR)
81 Convert a string representing an unsigned decimal number to an
82 object representing the same number. The input is normalized, i.e.,
83 it matches "^(0|[1-9]\d*)$".
84 CLASS->_zero()
86 Return an object representing the number zero.
87 CLASS->_one()
89 Return an object representing the number one.
90 CLASS->_two()
92 Return an object representing the number two.
93 CLASS->_ten()
95 Return an object representing the number ten.
96 CLASS->_from_bin(STR)
98 Return an object given a string representing a binary number. The
99 input has a '0b' prefix and matches the regular expression
100 "^0[bB](0|1[01]*)$".
101 CLASS->_from_oct(STR)
103 Return an object given a string representing an octal number. The
104 input has a '0' prefix and matches the regular expression
105 "^0[1-7]*$".
106 CLASS->_from_hex(STR)
108 Return an object given a string representing a hexadecimal number.
109 The input has a '0x' prefix and matches the regular expression
110 "^0x(0|[1-9a-fA-F][\da-fA-F]*)$".
111 CLASS->_from_bytes(STR)
113 Returns an object given a byte string representing the number. The
114 byte string is in big endian byte order, so the two-byte input
115 string "\x01\x00" should give an output value representing the
116 number 256.
117 CLASS->_from_base(STR, BASE, COLLSEQ)
119 Returns an object given a string STR, a base BASE, and a collation
120 sequence COLLSEQ. Each character in STR represents a numerical
121 value identical to the character's position in COLLSEQ. All
122 characters in STR must be present in COLLSEQ.
123 If BASE is less than or equal to 94, and a collation sequence is
125 not specified, the following default collation sequence is used. It
126 contains of all the 94 printable ASCII characters except
127 space/blank:
128 0123456789 # ASCII 48 to 57
130 ABCDEFGHIJKLMNOPQRSTUVWXYZ # ASCII 65 to 90
131 abcdefghijklmnopqrstuvwxyz # ASCII 97 to 122
132 !"#$%&'()*+,-./ # ASCII 33 to 47
133 :;<=>?@ # ASCII 58 to 64
134 [\]^_` # ASCII 91 to 96
135 {|}~ # ASCII 123 to 126
136 If the default collation sequence is used, and the BASE is less
138 than or equal to 36, the letter case in STR is ignored.
139 For instance, with base 3 and collation sequence "-/|", the
141 character "-" represents 0, "/" represents 1, and "|" represents 2.
142 So if STR is "/|-", the output is 1 * 3**2 + 2 * 3**1 + 0 * 3**0 =
143 15.
144 The following examples show standard binary, octal, decimal, and
146 hexadecimal conversion. All examples return 250.
147 $x = $class -> _from_base("11111010", 2)
149 $x = $class -> _from_base("372", 8)
150 $x = $class -> _from_base("250", 10)
151 $x = $class -> _from_base("FA", 16)
152 Some more examples, all returning 250:
154 $x = $class -> _from_base("100021", 3)
156 $x = $class -> _from_base("3322", 4)
157 $x = $class -> _from_base("2000", 5)
158 $x = $class -> _from_base("caaa", 5, "abcde")
159 $x = $class -> _from_base("42", 62)
160 $x = $class -> _from_base("2!", 94)
161 CLASS->_from_base_num(ARRAY, BASE)
163 Returns an object given an array of values and a base. This method
164 is equivalent to _from_base(), but works on numbers in an array
165 rather than characters in a string. Unlike _from_base(), all input
166 values may be arbitrarily large.
167 $x = $class -> _from_base_num([1, 1, 0, 1], 2) # $x is 13
169 $x = $class -> _from_base_num([3, 125, 39], 128) # $x is 65191
170 Mathematical functions
172 CLASS->_add(OBJ1, OBJ2)
174 Addition. Returns the result of adding OBJ2 to OBJ1.
175 CLASS->_mul(OBJ1, OBJ2)
177 Multiplication. Returns the result of multiplying OBJ2 and OBJ1.
178 CLASS->_div(OBJ1, OBJ2)
180 Division. In scalar context, returns the quotient after dividing
181 OBJ1 by OBJ2 and truncating the result to an integer. In list
182 context, return the quotient and the remainder.
183 CLASS->_sub(OBJ1, OBJ2, FLAG)
185 CLASS->_sub(OBJ1, OBJ2)
186 Subtraction. Returns the result of subtracting OBJ2 by OBJ1. If
187 "flag" is false or omitted, OBJ1 might be modified. If "flag" is
188 true, OBJ2 might be modified.
189 CLASS->_sadd(OBJ1, SIGN1, OBJ2, SIGN2)
191 Signed addition. Returns the result of adding OBJ2 with sign SIGN2
192 to OBJ1 with sign SIGN1.
193 ($obj3, $sign3) = $class -> _sadd($obj1, $sign1, $obj2, $sign2);
195 CLASS->_ssub(OBJ1, SIGN1, OBJ2, SIGN2)
197 Signed subtraction. Returns the result of subtracting OBJ2 with
198 sign SIGN2 to OBJ1 with sign SIGN1.
199 ($obj3, $sign3) = $class -> _sadd($obj1, $sign1, $obj2, $sign2);
201 CLASS->_dec(OBJ)
203 Returns the result after decrementing OBJ by one.
204 CLASS->_inc(OBJ)
206 Returns the result after incrementing OBJ by one.
207 CLASS->_mod(OBJ1, OBJ2)
209 Returns OBJ1 modulo OBJ2, i.e., the remainder after dividing OBJ1
210 by OBJ2.
211 CLASS->_sqrt(OBJ)
213 Returns the square root of OBJ, truncated to an integer.
214 CLASS->_root(OBJ, N)
216 Returns the Nth root of OBJ, truncated to an integer.
217 CLASS->_fac(OBJ)
219 Returns the factorial of OBJ, i.e., the product of all positive
220 integers up to and including OBJ.
221 CLASS->_dfac(OBJ)
223 Returns the double factorial of OBJ. If OBJ is an even integer,
224 returns the product of all positive, even integers up to and
225 including OBJ, i.e., 2*4*6*...*OBJ. If OBJ is an odd integer,
226 returns the product of all positive, odd integers, i.e.,
227 1*3*5*...*OBJ.
228 CLASS->_pow(OBJ1, OBJ2)
230 Returns OBJ1 raised to the power of OBJ2. By convention, 0**0 = 1.
231 CLASS->_modinv(OBJ1, OBJ2)
233 Returns the modular multiplicative inverse, i.e., return OBJ3 so
234 that
235 (OBJ3 * OBJ1) % OBJ2 = 1 % OBJ2
237 The result is returned as two arguments. If the modular
239 multiplicative inverse does not exist, both arguments are
240 undefined. Otherwise, the arguments are a number (object) and its
241 sign ("+" or "-").
242 The output value, with its sign, must either be a positive value in
244 the range 1,2,...,OBJ2-1 or the same value subtracted OBJ2. For
245 instance, if the input arguments are objects representing the
246 numbers 7 and 5, the method must either return an object
247 representing the number 3 and a "+" sign, since (3*7) % 5 = 1 % 5,
248 or an object representing the number 2 and a "-" sign, since (-2*7)
249 % 5 = 1 % 5.
250 CLASS->_modpow(OBJ1, OBJ2, OBJ3)
252 Returns the modular exponentiation, i.e., (OBJ1 ** OBJ2) % OBJ3.
253 CLASS->_rsft(OBJ, N, B)
255 Returns the result after shifting OBJ N digits to thee right in
256 base B. This is equivalent to performing integer division by B**N
257 and discarding the remainder, except that it might be much faster.
258 For instance, if the object $obj represents the hexadecimal number
260 0xabcde, then "_rsft($obj, 2, 16)" returns an object representing
261 the number 0xabc. The "remainer", 0xde, is discarded and not
262 returned.
263 CLASS->_lsft(OBJ, N, B)
265 Returns the result after shifting OBJ N digits to the left in base
266 B. This is equivalent to multiplying by B**N, except that it might
267 be much faster.
268 CLASS->_log_int(OBJ, B)
270 Returns the logarithm of OBJ to base BASE truncted to an integer.
271 This method has two output arguments, the OBJECT and a STATUS. The
272 STATUS is Perl scalar; it is 1 if OBJ is the exact result, 0 if the
273 result was truncted to give OBJ, and undef if it is unknown whether
274 OBJ is the exact result.
275 CLASS->_gcd(OBJ1, OBJ2)
277 Returns the greatest common divisor of OBJ1 and OBJ2.
278 CLASS->_lcm(OBJ1, OBJ2)
280 Return the least common multiple of OBJ1 and OBJ2.
281 CLASS->_fib(OBJ)
283 In scalar context, returns the nth Fibonacci number: _fib(0)
284 returns 0, _fib(1) returns 1, _fib(2) returns 1, _fib(3) returns 2
285 etc. In list context, returns the Fibonacci numbers from F(0) to
286 F(n): 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, ...
287 CLASS->_lucas(OBJ)
289 In scalar context, returns the nth Lucas number: _lucas(0) returns
290 2, _lucas(1) returns 1, _lucas(2) returns 3, etc. In list context,
291 returns the Lucas numbers from L(0) to L(n): 2, 1, 3, 4, 7, 11, 18,
292 29,47, 76, ...
293 Bitwise operators
295 CLASS->_and(OBJ1, OBJ2)
297 Returns bitwise and.
298 CLASS->_or(OBJ1, OBJ2)
300 Returns bitwise or.
301 CLASS->_xor(OBJ1, OBJ2)
303 Returns bitwise exclusive or.
304 CLASS->_sand(OBJ1, OBJ2, SIGN1, SIGN2)
306 Returns bitwise signed and.
307 CLASS->_sor(OBJ1, OBJ2, SIGN1, SIGN2)
309 Returns bitwise signed or.
310 CLASS->_sxor(OBJ1, OBJ2, SIGN1, SIGN2)
312 Returns bitwise signed exclusive or.
313 Boolean operators
315 CLASS->_is_zero(OBJ)
317 Returns a true value if OBJ is zero, and false value otherwise.
318 CLASS->_is_one(OBJ)
320 Returns a true value if OBJ is one, and false value otherwise.
321 CLASS->_is_two(OBJ)
323 Returns a true value if OBJ is two, and false value otherwise.
324 CLASS->_is_ten(OBJ)
326 Returns a true value if OBJ is ten, and false value otherwise.
327 CLASS->_is_even(OBJ)
329 Return a true value if OBJ is an even integer, and a false value
330 otherwise.
331 CLASS->_is_odd(OBJ)
333 Return a true value if OBJ is an even integer, and a false value
334 otherwise.
335 CLASS->_acmp(OBJ1, OBJ2)
337 Compare OBJ1 and OBJ2 and return -1, 0, or 1, if OBJ1 is
338 numerically less than, equal to, or larger than OBJ2, respectively.
339 String conversion
341 CLASS->_str(OBJ)
343 Returns a string representing OBJ in decimal notation. The returned
344 string should have no leading zeros, i.e., it should match
345 "^(0|[1-9]\d*)$".
346 CLASS->_to_bin(OBJ)
348 Returns the binary string representation of OBJ.
349 CLASS->_to_oct(OBJ)
351 Returns the octal string representation of the number.
352 CLASS->_to_hex(OBJ)
354 Returns the hexadecimal string representation of the number.
355 CLASS->_to_bytes(OBJ)
357 Returns a byte string representation of OBJ. The byte string is in
358 big endian byte order, so if OBJ represents the number 256, the
359 output should be the two-byte string "\x01\x00".
360 CLASS->_to_base(OBJ, BASE, COLLSEQ)
362 Returns a string representation of OBJ in base BASE with collation
363 sequence COLLSEQ.
364 $val = $class -> _new("210");
366 $str = $class -> _to_base($val, 10, "xyz") # $str is "zyx"
367 $val = $class -> _new("32");
369 $str = $class -> _to_base($val, 2, "-|") # $str is "|-----"
370 See _from_base() for more information.
372 CLASS->_to_base_num(OBJ, BASE)
374 Converts the given number to the given base. This method is
375 equivalent to _to_base(), but returns numbers in an array rather
376 than characters in a string. In the output, the first element is
377 the most significant. Unlike _to_base(), all input values may be
378 arbitrarily large.
379 $x = $class -> _to_base_num(13, 2) # $x is [1, 1, 0, 1]
381 $x = $class -> _to_base_num(65191, 128) # $x is [3, 125, 39]
382 CLASS->_as_bin(OBJ)
384 Like _to_bin() but with a '0b' prefix.
385 CLASS->_as_oct(OBJ)
387 Like _to_oct() but with a '0' prefix.
388 CLASS->_as_hex(OBJ)
390 Like _to_hex() but with a '0x' prefix.
391 CLASS->_as_bytes(OBJ)
393 This is an alias to _to_bytes().
394 Numeric conversion
396 CLASS->_num(OBJ)
398 Returns a Perl scalar number representing the number OBJ as close
399 as possible. Since Perl scalars have limited precision, the
400 returned value might not be exactly the same as OBJ.
401 Miscellaneous
403 CLASS->_copy(OBJ)
405 Returns a true copy OBJ.
406 CLASS->_len(OBJ)
408 Returns the number of the decimal digits in OBJ. The output is a
409 Perl scalar.
410 CLASS->_zeros(OBJ)
412 Returns the number of trailing decimal zeros. The output is a Perl
413 scalar. The number zero has no trailing decimal zeros.
414 CLASS->_digit(OBJ, N)
416 Returns the Nth digit in OBJ as a Perl scalar. N is a Perl scalar,
417 where zero refers to the rightmost (least significant) digit, and
418 negative values count from the left (most significant digit). If
419 $obj represents the number 123, then
420 CLASS->_digit($obj, 0) # returns 3
422 CLASS->_digit($obj, 1) # returns 2
423 CLASS->_digit($obj, 2) # returns 1
424 CLASS->_digit($obj, -1) # returns 1
425 CLASS->_digitsum(OBJ)
427 Returns the sum of the base 10 digits.
428 CLASS->_check(OBJ)
430 Returns true if the object is invalid and false otherwise.
431 Preferably, the true value is a string describing the problem with
432 the object. This is a check routine to test the internal state of
433 the object for corruption.
434 CLASS->_set(OBJ)
436 xxx
437 API version 2
439 The following methods are required for an API version of 2 or greater.
440 Constructors
442 CLASS->_1ex(N)
444 Return an object representing the number 10**N where N >= 0 is a
445 Perl scalar.
446 Mathematical functions
448 CLASS->_nok(OBJ1, OBJ2)
450 Return the binomial coefficient OBJ1 over OBJ1.
451 Miscellaneous
453 CLASS->_alen(OBJ)
455 Return the approximate number of decimal digits of the object. The
456 output is a Perl scalar.
457
459 If you want to port your own favourite C library for big numbers to the
460 Math::BigInt interface, you can take any of the already existing
461 modules as a rough guideline. You should really wrap up the latest
462 Math::BigInt and Math::BigFloat testsuites with your module, and
463 replace in them any of the following:
464 use Math::BigInt;
466 by this:
468 use Math::BigInt lib => 'yourlib';
470 This way you ensure that your library really works 100% within
472 Math::BigInt.
473
475 Please report any bugs or feature requests to "bug-math-bigint at
476 rt.cpan.org", or through the web interface at
477 <https://rt.cpan.org/Ticket/Create.html?Queue=Math-BigInt> (requires
478 login). We will be notified, and then you'll automatically be notified
479 of progress on your bug as I make changes.
480
482 You can find documentation for this module with the perldoc command.
483 perldoc Math::BigInt::Calc
485 You can also look for information at:
487 • GitHub Source Repository
489 <https://github.com/pjacklam/p5-Math-BigInt>
491 • RT: CPAN's request tracker
493 <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-BigInt>
495 • MetaCPAN
497 <https://metacpan.org/release/Math-BigInt>
499 • CPAN Testers Matrix
501 <http://matrix.cpantesters.org/?dist=Math-BigInt>
503
505 This program is free software; you may redistribute it and/or modify it
506 under the same terms as Perl itself.
507
509 Peter John Acklam, <pjacklam@gmail.com>
510 Code and documentation based on the Math::BigInt::Calc module by Tels
512 <nospam-abuse@bloodgate.com>
513
515 Math::BigInt, Math::BigInt::Calc, Math::BigInt::GMP,
516 Math::BigInt::FastCalc and Math::BigInt::Pari.
517perl v5.36.1 2023-07-17 Math::BigInt::Lib(3)