1Math::BigInt::Lib(3)  User Contributed Perl Documentation Math::BigInt::Lib(3)
2
3
4

NAME

6       Math::BigInt::Lib - virtual parent class for Math::BigInt libraries
7

SYNOPSIS

9           # In the backend library for Math::BigInt et al.
10
11           package Math::BigInt::MyBackend;
12
13           use Math::BigInt::Lib;
14           our @ISA = qw< Math::BigInt::Lib >;
15
16           sub _new { ... }
17           sub _str { ... }
18           sub _add { ... }
19           str _sub { ... }
20           ...
21
22           # In your main program.
23
24           use Math::BigInt lib => 'MyBackend';
25

DESCRIPTION

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
32       Other backend libraries include Math::BigInt::Calc,
33       Math::BigInt::FastCalc, Math::BigInt::GMP, and Math::BigInt::Pari.
34
35       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
40               use Math::BigInt lib => 'libname';
41
42       'libname' is either the long name, like 'Math::BigInt::Pari', or only
43       the short version, like 'Pari'.
44
45   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
49       division by zero (e.g., in "_div()" and "_mod()")) or similar cases.
50
51       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
56           $x = Class -> method($x, $y);     # like this
57           $x = $x -> method($y);            # not like this ...
58           $x -> method($y);                 # ... or like this
59
60       And with boolean methods
61
62           $bool = Class -> method($x, $y);  # like this
63           $bool = $x -> method($y);         # not like this
64
65       Return values are always objects, strings, Perl scalars, or true/false
66       for comparison routines.
67
68       API version
69
70       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
74       Constructors
75
76       The following methods are mandatory: _new(), _str(), _add(), and
77       _sub().  However, computations will be very slow without _mul() and
78       _div().
79
80       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
85       CLASS->_zero()
86           Return an object representing the number zero.
87
88       CLASS->_one()
89           Return an object representing the number one.
90
91       CLASS->_two()
92           Return an object representing the number two.
93
94       CLASS->_ten()
95           Return an object representing the number ten.
96
97       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
102       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
107       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
112       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
118       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
124           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
129               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
137           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
140           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
145           The following examples show standard binary, octal, decimal, and
146           hexadecimal conversion. All examples return 250.
147
148               $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
153           Some more examples, all returning 250:
154
155               $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
162       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
166           input values may be arbitrarily large.
167
168               $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
171       Mathematical functions
172
173       CLASS->_add(OBJ1, OBJ2)
174           Addition. Returns the result of adding OBJ2 to OBJ1.
175
176       CLASS->_mul(OBJ1, OBJ2)
177           Multiplication. Returns the result of multiplying OBJ2 and OBJ1.
178
179       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
184       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
190       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
194               ($obj3, $sign3) = $class -> _sadd($obj1, $sign1, $obj2, $sign2);
195
196       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
200               ($obj3, $sign3) = $class -> _sadd($obj1, $sign1, $obj2, $sign2);
201
202       CLASS->_dec(OBJ)
203           Returns the result after decrementing OBJ by one.
204
205       CLASS->_inc(OBJ)
206           Returns the result after incrementing OBJ by one.
207
208       CLASS->_mod(OBJ1, OBJ2)
209           Returns OBJ1 modulo OBJ2, i.e., the remainder after dividing OBJ1
210           by OBJ2.
211
212       CLASS->_sqrt(OBJ)
213           Returns the square root of OBJ, truncated to an integer.
214
215       CLASS->_root(OBJ, N)
216           Returns the Nth root of OBJ, truncated to an integer.
217
218       CLASS->_fac(OBJ)
219           Returns the factorial of OBJ, i.e., the product of all positive
220           integers up to and including OBJ.
221
222       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
229       CLASS->_pow(OBJ1, OBJ2)
230           Returns OBJ1 raised to the power of OBJ2. By convention, 0**0 = 1.
231
232       CLASS->_modinv(OBJ1, OBJ2)
233           Returns the modular multiplicative inverse, i.e., return OBJ3 so
234           that
235
236               (OBJ3 * OBJ1) % OBJ2 = 1 % OBJ2
237
238           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
243           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
251       CLASS->_modpow(OBJ1, OBJ2, OBJ3)
252           Returns the modular exponentiation, i.e., (OBJ1 ** OBJ2) % OBJ3.
253
254       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
259           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
264       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
269       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
276       CLASS->_gcd(OBJ1, OBJ2)
277           Returns the greatest common divisor of OBJ1 and OBJ2.
278
279       CLASS->_lcm(OBJ1, OBJ2)
280           Return the least common multiple of OBJ1 and OBJ2.
281
282       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
288       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
294       Bitwise operators
295
296       CLASS->_and(OBJ1, OBJ2)
297           Returns bitwise and.
298
299       CLASS->_or(OBJ1, OBJ2)
300           Returns bitwise or.
301
302       CLASS->_xor(OBJ1, OBJ2)
303           Returns bitwise exclusive or.
304
305       CLASS->_sand(OBJ1, OBJ2, SIGN1, SIGN2)
306           Returns bitwise signed and.
307
308       CLASS->_sor(OBJ1, OBJ2, SIGN1, SIGN2)
309           Returns bitwise signed or.
310
311       CLASS->_sxor(OBJ1, OBJ2, SIGN1, SIGN2)
312           Returns bitwise signed exclusive or.
313
314       Boolean operators
315
316       CLASS->_is_zero(OBJ)
317           Returns a true value if OBJ is zero, and false value otherwise.
318
319       CLASS->_is_one(OBJ)
320           Returns a true value if OBJ is one, and false value otherwise.
321
322       CLASS->_is_two(OBJ)
323           Returns a true value if OBJ is two, and false value otherwise.
324
325       CLASS->_is_ten(OBJ)
326           Returns a true value if OBJ is ten, and false value otherwise.
327
328       CLASS->_is_even(OBJ)
329           Return a true value if OBJ is an even integer, and a false value
330           otherwise.
331
332       CLASS->_is_odd(OBJ)
333           Return a true value if OBJ is an even integer, and a false value
334           otherwise.
335
336       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
340       String conversion
341
342       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
347       CLASS->_to_bin(OBJ)
348           Returns the binary string representation of OBJ.
349
350       CLASS->_to_oct(OBJ)
351           Returns the octal string representation of the number.
352
353       CLASS->_to_hex(OBJ)
354           Returns the hexadecimal string representation of the number.
355
356       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
361       CLASS->_to_base(OBJ, BASE, COLLSEQ)
362           Returns a string representation of OBJ in base BASE with collation
363           sequence COLLSEQ.
364
365               $val = $class -> _new("210");
366               $str = $class -> _to_base($val, 10, "xyz")  # $str is "zyx"
367
368               $val = $class -> _new("32");
369               $str = $class -> _to_base($val, 2, "-|")  # $str is "|-----"
370
371           See _from_base() for more information.
372
373       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
380               $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
383       CLASS->_as_bin(OBJ)
384           Like "_to_bin()" but with a '0b' prefix.
385
386       CLASS->_as_oct(OBJ)
387           Like "_to_oct()" but with a '0' prefix.
388
389       CLASS->_as_hex(OBJ)
390           Like "_to_hex()" but with a '0x' prefix.
391
392       CLASS->_as_bytes(OBJ)
393           This is an alias to "_to_bytes()".
394
395       Numeric conversion
396
397       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
402       Miscellaneous
403
404       CLASS->_copy(OBJ)
405           Returns a true copy OBJ.
406
407       CLASS->_len(OBJ)
408           Returns the number of the decimal digits in OBJ. The output is a
409           Perl scalar.
410
411       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
415       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
421               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
426       CLASS->_digitsum(OBJ)
427           Returns the sum of the base 10 digits.
428
429       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
435       CLASS->_set(OBJ)
436           xxx
437
438   API version 2
439       The following methods are required for an API version of 2 or greater.
440
441       Constructors
442
443       CLASS->_1ex(N)
444           Return an object representing the number 10**N where N >= 0 is a
445           Perl scalar.
446
447       Mathematical functions
448
449       CLASS->_nok(OBJ1, OBJ2)
450           Return the binomial coefficient OBJ1 over OBJ1.
451
452       Miscellaneous
453
454       CLASS->_alen(OBJ)
455           Return the approximate number of decimal digits of the object. The
456           output is a Perl scalar.
457

WRAP YOUR OWN

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
465               use Math::BigInt;
466
467       by this:
468
469               use Math::BigInt lib => 'yourlib';
470
471       This way you ensure that your library really works 100% within
472       Math::BigInt.
473

BUGS

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

SUPPORT

482       You can find documentation for this module with the perldoc command.
483
484           perldoc Math::BigInt::Calc
485
486       You can also look for information at:
487
488       •   RT: CPAN's request tracker
489
490           <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-BigInt>
491
492       •   AnnoCPAN: Annotated CPAN documentation
493
494           <http://annocpan.org/dist/Math-BigInt>
495
496       •   CPAN Ratings
497
498           <https://cpanratings.perl.org/dist/Math-BigInt>
499
500       •   MetaCPAN
501
502           <https://metacpan.org/release/Math-BigInt>
503
504       •   CPAN Testers Matrix
505
506           <http://matrix.cpantesters.org/?dist=Math-BigInt>
507
508       •   The Bignum mailing list
509
510           •   Post to mailing list
511
512               "bignum at lists.scsys.co.uk"
513
514           •   View mailing list
515
516               <http://lists.scsys.co.uk/pipermail/bignum/>
517
518           •   Subscribe/Unsubscribe
519
520               <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
521

LICENSE

523       This program is free software; you may redistribute it and/or modify it
524       under the same terms as Perl itself.
525

AUTHOR

527       Peter John Acklam, <pjacklam@gmail.com>
528
529       Code and documentation based on the Math::BigInt::Calc module by Tels
530       <nospam-abuse@bloodgate.com>
531

SEE ALSO

533       Math::BigInt, Math::BigInt::Calc, Math::BigInt::GMP,
534       Math::BigInt::FastCalc and Math::BigInt::Pari.
535
536
537
538perl v5.36.0                      2022-07-22              Math::BigInt::Lib(3)