Math::BigInt::Lib(3pm)

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

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

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

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       Mathematical functions
163
164       CLASS->_add(OBJ1, OBJ2)
165           Returns the result of adding OBJ2 to OBJ1.
166
167       CLASS->_mul(OBJ1, OBJ2)
168           Returns the result of multiplying OBJ2 and OBJ1.
169
170       CLASS->_div(OBJ1, OBJ2)
171           In scalar context, returns the quotient after dividing OBJ1 by OBJ2
172           and truncating the result to an integer. In list context, return
173           the quotient and the remainder.
174
175       CLASS->_sub(OBJ1, OBJ2, FLAG)
176       CLASS->_sub(OBJ1, OBJ2)
177           Returns the result of subtracting OBJ2 by OBJ1. If "flag" is false
178           or omitted, OBJ1 might be modified. If "flag" is true, OBJ2 might
179           be modified.
180
181       CLASS->_dec(OBJ)
182           Returns the result after decrementing OBJ by one.
183
184       CLASS->_inc(OBJ)
185           Returns the result after incrementing OBJ by one.
186
187       CLASS->_mod(OBJ1, OBJ2)
188           Returns OBJ1 modulo OBJ2, i.e., the remainder after dividing OBJ1
189           by OBJ2.
190
191       CLASS->_sqrt(OBJ)
192           Returns the square root of OBJ, truncated to an integer.
193
194       CLASS->_root(OBJ, N)
195           Returns the Nth root of OBJ, truncated to an integer.
196
197       CLASS->_fac(OBJ)
198           Returns the factorial of OBJ, i.e., the product of all positive
199           integers up to and including OBJ.
200
201       CLASS->_dfac(OBJ)
202           Returns the double factorial of OBJ. If OBJ is an even integer,
203           returns the product of all positive, even integers up to and
204           including OBJ, i.e., 2*4*6*...*OBJ. If OBJ is an odd integer,
205           returns the product of all positive, odd integers, i.e.,
206           1*3*5*...*OBJ.
207
208       CLASS->_pow(OBJ1, OBJ2)
209           Returns OBJ1 raised to the power of OBJ2. By convention, 0**0 = 1.
210
211       CLASS->_modinv(OBJ1, OBJ2)
212           Returns the modular multiplicative inverse, i.e., return OBJ3 so
213           that
214
215               (OBJ3 * OBJ1) % OBJ2 = 1 % OBJ2
216
217           The result is returned as two arguments. If the modular
218           multiplicative inverse does not exist, both arguments are
219           undefined. Otherwise, the arguments are a number (object) and its
220           sign ("+" or "-").
221
222           The output value, with its sign, must either be a positive value in
223           the range 1,2,...,OBJ2-1 or the same value subtracted OBJ2. For
224           instance, if the input arguments are objects representing the
225           numbers 7 and 5, the method must either return an object
226           representing the number 3 and a "+" sign, since (3*7) % 5 = 1 % 5,
227           or an object representing the number 2 and a "-" sign, since (-2*7)
228           % 5 = 1 % 5.
229
230       CLASS->_modpow(OBJ1, OBJ2, OBJ3)
231           Returns the modular exponentiation, i.e., (OBJ1 ** OBJ2) % OBJ3.
232
233       CLASS->_rsft(OBJ, N, B)
234           Returns the result after shifting OBJ N digits to thee right in
235           base B. This is equivalent to performing integer division by B**N
236           and discarding the remainder, except that it might be much faster.
237
238           For instance, if the object $obj represents the hexadecimal number
239           0xabcde, then "_rsft($obj, 2, 16)" returns an object representing
240           the number 0xabc. The "remainer", 0xde, is discarded and not
241           returned.
242
243       CLASS->_lsft(OBJ, N, B)
244           Returns the result after shifting OBJ N digits to the left in base
245           B. This is equivalent to multiplying by B**N, except that it might
246           be much faster.
247
248       CLASS->_log_int(OBJ, B)
249           Returns the logarithm of OBJ to base BASE truncted to an integer.
250           This method has two output arguments, the OBJECT and a STATUS. The
251           STATUS is Perl scalar; it is 1 if OBJ is the exact result, 0 if the
252           result was truncted to give OBJ, and undef if it is unknown whether
253           OBJ is the exact result.
254
255       CLASS->_gcd(OBJ1, OBJ2)
256           Returns the greatest common divisor of OBJ1 and OBJ2.
257
258       CLASS->_lcm(OBJ1, OBJ2)
259           Return the least common multiple of OBJ1 and OBJ2.
260
261       CLASS->_fib(OBJ)
262           In scalar context, returns the nth Fibonacci number: _fib(0)
263           returns 0, _fib(1) returns 1, _fib(2) returns 1, _fib(3) returns 2
264           etc. In list context, returns the Fibonacci numbers from F(0) to
265           F(n): 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, ...
266
267       CLASS->_lucas(OBJ)
268           In scalar context, returns the nth Lucas number: _lucas(0) returns
269           2, _lucas(1) returns 1, _lucas(2) returns 3, etc. In list context,
270           returns the Lucas numbers from L(0) to L(n): 2, 1, 3, 4, 7, 11, 18,
271           29,47, 76, ...
272
273       Bitwise operators
274
275       CLASS->_and(OBJ1, OBJ2)
276           Returns bitwise and.
277
278       CLASS->_or(OBJ1, OBJ2)
279           Returns bitwise or.
280
281       CLASS->_xor(OBJ1, OBJ2)
282           Returns bitwise exclusive or.
283
284       CLASS->_sand(OBJ1, OBJ2, SIGN1, SIGN2)
285           Returns bitwise signed and.
286
287       CLASS->_sor(OBJ1, OBJ2, SIGN1, SIGN2)
288           Returns bitwise signed or.
289
290       CLASS->_sxor(OBJ1, OBJ2, SIGN1, SIGN2)
291           Returns bitwise signed exclusive or.
292
293       Boolean operators
294
295       CLASS->_is_zero(OBJ)
296           Returns a true value if OBJ is zero, and false value otherwise.
297
298       CLASS->_is_one(OBJ)
299           Returns a true value if OBJ is one, and false value otherwise.
300
301       CLASS->_is_two(OBJ)
302           Returns a true value if OBJ is two, and false value otherwise.
303
304       CLASS->_is_ten(OBJ)
305           Returns a true value if OBJ is ten, and false value otherwise.
306
307       CLASS->_is_even(OBJ)
308           Return a true value if OBJ is an even integer, and a false value
309           otherwise.
310
311       CLASS->_is_odd(OBJ)
312           Return a true value if OBJ is an even integer, and a false value
313           otherwise.
314
315       CLASS->_acmp(OBJ1, OBJ2)
316           Compare OBJ1 and OBJ2 and return -1, 0, or 1, if OBJ1 is
317           numerically less than, equal to, or larger than OBJ2, respectively.
318
319       String conversion
320
321       CLASS->_str(OBJ)
322           Returns a string representing OBJ in decimal notation. The returned
323           string should have no leading zeros, i.e., it should match
324           "^(0|[1-9]\d*)$".
325
326       CLASS->_to_bin(OBJ)
327           Returns the binary string representation of OBJ.
328
329       CLASS->_to_oct(OBJ)
330           Returns the octal string representation of the number.
331
332       CLASS->_to_hex(OBJ)
333           Returns the hexadecimal string representation of the number.
334
335       CLASS->_to_bytes(OBJ)
336           Returns a byte string representation of OBJ. The byte string is in
337           big endian byte order, so if OBJ represents the number 256, the
338           output should be the two-byte string "\x01\x00".
339
340       CLASS->_to_base(OBJ, BASE, COLLSEQ)
341           Returns a string representation of OBJ in base BASE with collation
342           sequence COLLSEQ.
343
344               $val = $class -> _new("210");
345               $str = $class -> _to_base($val, 10, "xyz")  # $str is "zyx"
346
347               $val = $class -> _new("32");
348               $str = $class -> _to_base($val, 2, "-|")  # $str is "|-----"
349
350           See _from_base() for more information.
351
352       CLASS->_as_bin(OBJ)
353           Like "_to_bin()" but with a '0b' prefix.
354
355       CLASS->_as_oct(OBJ)
356           Like "_to_oct()" but with a '0' prefix.
357
358       CLASS->_as_hex(OBJ)
359           Like "_to_hex()" but with a '0x' prefix.
360
361       CLASS->_as_bytes(OBJ)
362           This is an alias to "_to_bytes()".
363
364       Numeric conversion
365
366       CLASS->_num(OBJ)
367           Returns a Perl scalar number representing the number OBJ as close
368           as possible. Since Perl scalars have limited precision, the
369           returned value might not be exactly the same as OBJ.
370
371       Miscellaneous
372
373       CLASS->_copy(OBJ)
374           Returns a true copy OBJ.
375
376       CLASS->_len(OBJ)
377           Returns the number of the decimal digits in OBJ. The output is a
378           Perl scalar.
379
380       CLASS->_zeros(OBJ)
381           Returns the number of trailing decimal zeros. The output is a Perl
382           scalar. The number zero has no trailing decimal zeros.
383
384       CLASS->_digit(OBJ, N)
385           Returns the Nth digit in OBJ as a Perl scalar. N is a Perl scalar,
386           where zero refers to the rightmost (least significant) digit, and
387           negative values count from the left (most significant digit). If
388           $obj represents the number 123, then
389
390               CLASS->_digit($obj,  0)     # returns 3
391               CLASS->_digit($obj,  1)     # returns 2
392               CLASS->_digit($obj,  2)     # returns 1
393               CLASS->_digit($obj, -1)     # returns 1
394
395       CLASS->_digitsum(OBJ)
396           Returns the sum of the base 10 digits.
397
398       CLASS->_check(OBJ)
399           Returns true if the object is invalid and false otherwise.
400           Preferably, the true value is a string describing the problem with
401           the object. This is a check routine to test the internal state of
402           the object for corruption.
403
404       CLASS->_set(OBJ)
405           xxx
406
407   API version 2
408       The following methods are required for an API version of 2 or greater.
409
410       Constructors
411
412       CLASS->_1ex(N)
413           Return an object representing the number 10**N where N >= 0 is a
414           Perl scalar.
415
416       Mathematical functions
417
418       CLASS->_nok(OBJ1, OBJ2)
419           Return the binomial coefficient OBJ1 over OBJ1.
420
421       Miscellaneous
422
423       CLASS->_alen(OBJ)
424           Return the approximate number of decimal digits of the object. The
425           output is a Perl scalar.
426

428       If you want to port your own favourite C library for big numbers to the
429       Math::BigInt interface, you can take any of the already existing
430       modules as a rough guideline. You should really wrap up the latest
431       Math::BigInt and Math::BigFloat testsuites with your module, and
432       replace in them any of the following:
433
434               use Math::BigInt;
435
436       by this:
437
438               use Math::BigInt lib => 'yourlib';
439
440       This way you ensure that your library really works 100% within
441       Math::BigInt.
442

444       Please report any bugs or feature requests to "bug-math-bigint at
445       rt.cpan.org", or through the web interface at
446       <https://rt.cpan.org/Ticket/Create.html?Queue=Math-BigInt> (requires
447       login).  We will be notified, and then you'll automatically be notified
448       of progress on your bug as I make changes.
449

451       You can find documentation for this module with the perldoc command.
452
453           perldoc Math::BigInt::Calc
454
455       You can also look for information at:
456
457       ·   RT: CPAN's request tracker
458
459           <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-BigInt>
460
461       ·   AnnoCPAN: Annotated CPAN documentation
462
463           <http://annocpan.org/dist/Math-BigInt>
464
465       ·   CPAN Ratings
466
467           <https://cpanratings.perl.org/dist/Math-BigInt>
468
469       ·   MetaCPAN
470
471           <https://metacpan.org/release/Math-BigInt>
472
473       ·   CPAN Testers Matrix
474
475           <http://matrix.cpantesters.org/?dist=Math-BigInt>
476
477       ·   The Bignum mailing list
478
479           ·   Post to mailing list
480
481               "bignum at lists.scsys.co.uk"
482
483           ·   View mailing list
484
485               <http://lists.scsys.co.uk/pipermail/bignum/>
486
487           ·   Subscribe/Unsubscribe
488
489               <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
490

492       This program is free software; you may redistribute it and/or modify it
493       under the same terms as Perl itself.
494

496       Peter John Acklam, <pjacklam@online.no>
497
498       Code and documentation based on the Math::BigInt::Calc module by Tels
499       <nospam-abuse@bloodgate.com>
500

502       Math::BigInt, Math::BigInt::Calc, Math::BigInt::GMP,
503       Math::BigInt::FastCalc and Math::BigInt::Pari.
504
505
506
507perl v5.32.0                      2020-07-28              Math::BigInt::Lib(3)

NAME

SYNOPSIS

DESCRIPTION

WRAP YOUR OWN

BUGS

SUPPORT

LICENSE

AUTHOR

SEE ALSO