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           Return API version as a Perl scalar, 1 for Math::BigInt v1.70, 2
72           for Math::BigInt v1.83.
73
74           This method is no longer used. Methods that are not implemented by
75           a subclass will be inherited from this class.
76
77       Constructors
78
79       The following methods are mandatory: _new(), _str(), _add(), and
80       _sub().  However, computations will be very slow without _mul() and
81       _div().
82
83       CLASS->_new(STR)
84           Convert a string representing an unsigned decimal number to an
85           object representing the same number. The input is normalized, i.e.,
86           it matches "^(0|[1-9]\d*)$".
87
88       CLASS->_zero()
89           Return an object representing the number zero.
90
91       CLASS->_one()
92           Return an object representing the number one.
93
94       CLASS->_two()
95           Return an object representing the number two.
96
97       CLASS->_ten()
98           Return an object representing the number ten.
99
100       CLASS->_from_bin(STR)
101           Return an object given a string representing a binary number. The
102           input has a '0b' prefix and matches the regular expression
103           "^0[bB](0|1[01]*)$".
104
105       CLASS->_from_oct(STR)
106           Return an object given a string representing an octal number. The
107           input has a '0' prefix and matches the regular expression
108           "^0[1-7]*$".
109
110       CLASS->_from_hex(STR)
111           Return an object given a string representing a hexadecimal number.
112           The input has a '0x' prefix and matches the regular expression
113           "^0x(0|[1-9a-fA-F][\da-fA-F]*)$".
114
115       CLASS->_from_bytes(STR)
116           Returns an object given a byte string representing the number. The
117           byte string is in big endian byte order, so the two-byte input
118           string "\x01\x00" should give an output value representing the
119           number 256.
120
121       Mathematical functions
122
123       CLASS->_add(OBJ1, OBJ2)
124           Returns the result of adding OBJ2 to OBJ1.
125
126       CLASS->_mul(OBJ1, OBJ2)
127           Returns the result of multiplying OBJ2 and OBJ1.
128
129       CLASS->_div(OBJ1, OBJ2)
130           In scalar context, returns the quotient after dividing OBJ1 by OBJ2
131           and truncating the result to an integer. In list context, return
132           the quotient and the remainder.
133
134       CLASS->_sub(OBJ1, OBJ2, FLAG)
135       CLASS->_sub(OBJ1, OBJ2)
136           Returns the result of subtracting OBJ2 by OBJ1. If "flag" is false
137           or omitted, OBJ1 might be modified. If "flag" is true, OBJ2 might
138           be modified.
139
140       CLASS->_dec(OBJ)
141           Returns the result after decrementing OBJ by one.
142
143       CLASS->_inc(OBJ)
144           Returns the result after incrementing OBJ by one.
145
146       CLASS->_mod(OBJ1, OBJ2)
147           Returns OBJ1 modulo OBJ2, i.e., the remainder after dividing OBJ1
148           by OBJ2.
149
150       CLASS->_sqrt(OBJ)
151           Returns the square root of OBJ, truncated to an integer.
152
153       CLASS->_root(OBJ, N)
154           Returns the Nth root of OBJ, truncated to an integer.
155
156       CLASS->_fac(OBJ)
157           Returns the factorial of OBJ, i.e., the product of all positive
158           integers up to and including OBJ.
159
160       CLASS->_dfac(OBJ)
161           Returns the double factorial of OBJ. If OBJ is an even integer,
162           returns the product of all positive, even integers up to and
163           including OBJ, i.e., 2*4*6*...*OBJ. If OBJ is an odd integer,
164           returns the product of all positive, odd integers, i.e.,
165           1*3*5*...*OBJ.
166
167       CLASS->_pow(OBJ1, OBJ2)
168           Returns OBJ1 raised to the power of OBJ2. By convention, 0**0 = 1.
169
170       CLASS->_modinv(OBJ1, OBJ2)
171           Returns the modular multiplicative inverse, i.e., return OBJ3 so
172           that
173
174               (OBJ3 * OBJ1) % OBJ2 = 1 % OBJ2
175
176           The result is returned as two arguments. If the modular
177           multiplicative inverse does not exist, both arguments are
178           undefined. Otherwise, the arguments are a number (object) and its
179           sign ("+" or "-").
180
181           The output value, with its sign, must either be a positive value in
182           the range 1,2,...,OBJ2-1 or the same value subtracted OBJ2. For
183           instance, if the input arguments are objects representing the
184           numbers 7 and 5, the method must either return an object
185           representing the number 3 and a "+" sign, since (3*7) % 5 = 1 % 5,
186           or an object representing the number 2 and a "-" sign, since (-2*7)
187           % 5 = 1 % 5.
188
189       CLASS->_modpow(OBJ1, OBJ2, OBJ3)
190           Returns the modular exponentiation, i.e., (OBJ1 ** OBJ2) % OBJ3.
191
192       CLASS->_rsft(OBJ, N, B)
193           Returns the result after shifting OBJ N digits to thee right in
194           base B. This is equivalent to performing integer division by B**N
195           and discarding the remainder, except that it might be much faster.
196
197           For instance, if the object $obj represents the hexadecimal number
198           0xabcde, then "_rsft($obj, 2, 16)" returns an object representing
199           the number 0xabc. The "remainer", 0xde, is discarded and not
200           returned.
201
202       CLASS->_lsft(OBJ, N, B)
203           Returns the result after shifting OBJ N digits to the left in base
204           B. This is equivalent to multiplying by B**N, except that it might
205           be much faster.
206
207       CLASS->_log_int(OBJ, B)
208           Returns the logarithm of OBJ to base BASE truncted to an integer.
209           This method has two output arguments, the OBJECT and a STATUS. The
210           STATUS is Perl scalar; it is 1 if OBJ is the exact result, 0 if the
211           result was truncted to give OBJ, and undef if it is unknown whether
212           OBJ is the exact result.
213
214       CLASS->_gcd(OBJ1, OBJ2)
215           Returns the greatest common divisor of OBJ1 and OBJ2.
216
217       CLASS->_lcm(OBJ1, OBJ2)
218           Return the least common multiple of OBJ1 and OBJ2.
219
220       CLASS->_fib(OBJ)
221           In scalar context, returns the nth Fibonacci number: _fib(0)
222           returns 0, _fib(1) returns 1, _fib(2) returns 1, _fib(3) returns 2
223           etc. In list context, returns the Fibonacci numbers from F(0) to
224           F(n): 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, ...
225
226       CLASS->_lucas(OBJ)
227           In scalar context, returns the nth Lucas number: _lucas(0) returns
228           2, _lucas(1) returns 1, _lucas(2) returns 3, etc. In list context,
229           returns the Lucas numbers from L(0) to L(n): 2, 1, 3, 4, 7, 11, 18,
230           29,47, 76, ...
231
232       Bitwise operators
233
234       CLASS->_and(OBJ1, OBJ2)
235           Returns bitwise and.
236
237       CLASS->_or(OBJ1, OBJ2)
238           Return bitwise or.
239
240       CLASS->_xor(OBJ1, OBJ2)
241           Return bitwise exclusive or.
242
243       Boolean operators
244
245       CLASS->_is_zero(OBJ)
246           Returns a true value if OBJ is zero, and false value otherwise.
247
248       CLASS->_is_one(OBJ)
249           Returns a true value if OBJ is one, and false value otherwise.
250
251       CLASS->_is_two(OBJ)
252           Returns a true value if OBJ is two, and false value otherwise.
253
254       CLASS->_is_ten(OBJ)
255           Returns a true value if OBJ is ten, and false value otherwise.
256
257       CLASS->_is_even(OBJ)
258           Return a true value if OBJ is an even integer, and a false value
259           otherwise.
260
261       CLASS->_is_odd(OBJ)
262           Return a true value if OBJ is an even integer, and a false value
263           otherwise.
264
265       CLASS->_acmp(OBJ1, OBJ2)
266           Compare OBJ1 and OBJ2 and return -1, 0, or 1, if OBJ1 is
267           numerically less than, equal to, or larger than OBJ2, respectively.
268
269       String conversion
270
271       CLASS->_str(OBJ)
272           Returns a string representing OBJ in decimal notation. The returned
273           string should have no leading zeros, i.e., it should match
274           "^(0|[1-9]\d*)$".
275
276       CLASS->_to_bin(OBJ)
277           Returns the binary string representation of OBJ.
278
279       CLASS->_to_oct(OBJ)
280           Returns the octal string representation of the number.
281
282       CLASS->_to_hex(OBJ)
283           Returns the hexadecimal string representation of the number.
284
285       CLASS->_to_bytes(OBJ)
286           Returns a byte string representation of OBJ. The byte string is in
287           big endian byte order, so if OBJ represents the number 256, the
288           output should be the two-byte string "\x01\x00".
289
290       CLASS->_as_bin(OBJ)
291           Like "_to_bin()" but with a '0b' prefix.
292
293       CLASS->_as_oct(OBJ)
294           Like "_to_oct()" but with a '0' prefix.
295
296       CLASS->_as_hex(OBJ)
297           Like "_to_hex()" but with a '0x' prefix.
298
299       CLASS->_as_bytes(OBJ)
300           This is an alias to "_to_bytes()".
301
302       Numeric conversion
303
304       CLASS->_num(OBJ)
305           Returns a Perl scalar number representing the number OBJ as close
306           as possible. Since Perl scalars have limited precision, the
307           returned value might not be exactly the same as OBJ.
308
309       Miscellaneous
310
311       CLASS->_copy(OBJ)
312           Returns a true copy OBJ.
313
314       CLASS->_len(OBJ)
315           Returns the number of the decimal digits in OBJ. The output is a
316           Perl scalar.
317
318       CLASS->_zeros(OBJ)
319           Returns the number of trailing decimal zeros. The output is a Perl
320           scalar. The number zero has no trailing decimal zeros.
321
322       CLASS->_digit(OBJ, N)
323           Returns the Nth digit in OBJ as a Perl scalar. N is a Perl scalar,
324           where zero refers to the rightmost (least significant) digit, and
325           negative values count from the left (most significant digit). If
326           $obj represents the number 123, then
327
328               CLASS->_digit($obj,  0)     # returns 3
329               CLASS->_digit($obj,  1)     # returns 2
330               CLASS->_digit($obj,  2)     # returns 1
331               CLASS->_digit($obj, -1)     # returns 1
332
333       CLASS->_check(OBJ)
334           Returns true if the object is invalid and false otherwise.
335           Preferably, the true value is a string describing the problem with
336           the object. This is a check routine to test the internal state of
337           the object for corruption.
338
339       CLASS->_set(OBJ)
340           xxx
341
342   API version 2
343       The following methods are required for an API version of 2 or greater.
344
345       Constructors
346
347       CLASS->_1ex(N)
348           Return an object representing the number 10**N where N >= 0 is a
349           Perl scalar.
350
351       Mathematical functions
352
353       CLASS->_nok(OBJ1, OBJ2)
354           Return the binomial coefficient OBJ1 over OBJ1.
355
356       Miscellaneous
357
358       CLASS->_alen(OBJ)
359           Return the approximate number of decimal digits of the object. The
360           output is a Perl scalar.
361
362   API optional methods
363       The following methods are optional, and can be defined if the
364       underlying lib has a fast way to do them. If undefined, Math::BigInt
365       will use pure Perl (hence slow) fallback routines to emulate these:
366
367       Signed bitwise operators.
368
369       CLASS->_signed_or(OBJ1, OBJ2, SIGN1, SIGN2)
370           Return the signed bitwise or.
371
372       CLASS->_signed_and(OBJ1, OBJ2, SIGN1, SIGN2)
373           Return the signed bitwise and.
374
375       CLASS->_signed_xor(OBJ1, OBJ2, SIGN1, SIGN2)
376           Return the signed bitwise exclusive or.
377

WRAP YOUR OWN

379       If you want to port your own favourite C library for big numbers to the
380       Math::BigInt interface, you can take any of the already existing
381       modules as a rough guideline. You should really wrap up the latest
382       Math::BigInt and Math::BigFloat testsuites with your module, and
383       replace in them any of the following:
384
385               use Math::BigInt;
386
387       by this:
388
389               use Math::BigInt lib => 'yourlib';
390
391       This way you ensure that your library really works 100% within
392       Math::BigInt.
393

BUGS

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

SUPPORT

402       You can find documentation for this module with the perldoc command.
403
404           perldoc Math::BigInt::Calc
405
406       You can also look for information at:
407
408       ·   RT: CPAN's request tracker
409
410           <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-BigInt>
411
412       ·   AnnoCPAN: Annotated CPAN documentation
413
414           <http://annocpan.org/dist/Math-BigInt>
415
416       ·   CPAN Ratings
417
418           <http://cpanratings.perl.org/dist/Math-BigInt>
419
420       ·   Search CPAN
421
422           <http://search.cpan.org/dist/Math-BigInt/>
423
424       ·   CPAN Testers Matrix
425
426           <http://matrix.cpantesters.org/?dist=Math-BigInt>
427
428       ·   The Bignum mailing list
429
430           ·   Post to mailing list
431
432               "bignum at lists.scsys.co.uk"
433
434           ·   View mailing list
435
436               <http://lists.scsys.co.uk/pipermail/bignum/>
437
438           ·   Subscribe/Unsubscribe
439
440               <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
441

LICENSE

443       This program is free software; you may redistribute it and/or modify it
444       under the same terms as Perl itself.
445

AUTHOR

447       Peter John Acklam, <pjacklam@online.no>
448
449       Code and documentation based on the Math::BigInt::Calc module by Tels
450       <nospam-abuse@bloodgate.com>
451

SEE ALSO

453       Math::BigInt, Math::BigInt::Calc, Math::BigInt::GMP,
454       Math::BigInt::FastCalc and Math::BigInt::Pari.
455
456
457
458perl v5.28.1                      2018-04-18              Math::BigInt::Lib(3)
Impressum