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
49 division by 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 Return API version as a Perl scalar, 1 for Math::BigInt v1.70, 2
72 for Math::BigInt v1.83.
73 This method is no longer used. Methods that are not implemented by
75 a subclass will be inherited from this class.
76 Constructors
78 The following methods are mandatory: _new(), _str(), _add(), and
80 _sub(). However, computations will be very slow without _mul() and
81 _div().
82 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 CLASS->_zero()
89 Return an object representing the number zero.
90 CLASS->_one()
92 Return an object representing the number one.
93 CLASS->_two()
95 Return an object representing the number two.
96 CLASS->_ten()
98 Return an object representing the number ten.
99 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 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 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 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 CLASS->_from_base(STR, BASE, COLLSEQ)
122 Returns an object given a string STR, a base BASE, and a collation
123 sequence COLLSEQ. Each character in STR represents a numerical
124 value identical to the character's position in COLLSEQ. All
125 characters in STR must be present in COLLSEQ.
126 If BASE is less than or equal to 62, and a collation sequence is
128 not specified, a default collation sequence consisting of the 62
129 characters 0..9, A..Z, and a..z is used. If the default collation
130 sequence is used, and the BASE is less than or equal to 36, the
131 letter case in STR is ignored.
132 For instance, with base 3 and collation sequence "-/|", the
134 character "-" represents 0, "/" represents 1, and "|" represents 2.
135 So if STR is "/|-", the output is 1 * 3**2 + 2 * 3**1 + 0 * 3**0 =
136 15.
137 The following examples show standard binary, octal, decimal, and
139 hexadecimal conversion. All examples return 250.
140 $x = $class -> _from_base("11111010", 2)
142 $x = $class -> _from_base("372", 8)
143 $x = $class -> _from_base("250", 10)
144 $x = $class -> _from_base("FA", 16)
145 Some more examples, all returning 250:
147 $x = $class -> _from_base("100021", 3, "012")
149 $x = $class -> _from_base("3322", 4, "0123")
150 $x = $class -> _from_base("2000", 5, "01234")
151 $x = $class -> _from_base("caaa", 5, "abcde")
152 Mathematical functions
154 CLASS->_add(OBJ1, OBJ2)
156 Returns the result of adding OBJ2 to OBJ1.
157 CLASS->_mul(OBJ1, OBJ2)
159 Returns the result of multiplying OBJ2 and OBJ1.
160 CLASS->_div(OBJ1, OBJ2)
162 In scalar context, returns the quotient after dividing OBJ1 by OBJ2
163 and truncating the result to an integer. In list context, return
164 the quotient and the remainder.
165 CLASS->_sub(OBJ1, OBJ2, FLAG)
167 CLASS->_sub(OBJ1, OBJ2)
168 Returns the result of subtracting OBJ2 by OBJ1. If "flag" is false
169 or omitted, OBJ1 might be modified. If "flag" is true, OBJ2 might
170 be modified.
171 CLASS->_dec(OBJ)
173 Returns the result after decrementing OBJ by one.
174 CLASS->_inc(OBJ)
176 Returns the result after incrementing OBJ by one.
177 CLASS->_mod(OBJ1, OBJ2)
179 Returns OBJ1 modulo OBJ2, i.e., the remainder after dividing OBJ1
180 by OBJ2.
181 CLASS->_sqrt(OBJ)
183 Returns the square root of OBJ, truncated to an integer.
184 CLASS->_root(OBJ, N)
186 Returns the Nth root of OBJ, truncated to an integer.
187 CLASS->_fac(OBJ)
189 Returns the factorial of OBJ, i.e., the product of all positive
190 integers up to and including OBJ.
191 CLASS->_dfac(OBJ)
193 Returns the double factorial of OBJ. If OBJ is an even integer,
194 returns the product of all positive, even integers up to and
195 including OBJ, i.e., 2*4*6*...*OBJ. If OBJ is an odd integer,
196 returns the product of all positive, odd integers, i.e.,
197 1*3*5*...*OBJ.
198 CLASS->_pow(OBJ1, OBJ2)
200 Returns OBJ1 raised to the power of OBJ2. By convention, 0**0 = 1.
201 CLASS->_modinv(OBJ1, OBJ2)
203 Returns the modular multiplicative inverse, i.e., return OBJ3 so
204 that
205 (OBJ3 * OBJ1) % OBJ2 = 1 % OBJ2
207 The result is returned as two arguments. If the modular
209 multiplicative inverse does not exist, both arguments are
210 undefined. Otherwise, the arguments are a number (object) and its
211 sign ("+" or "-").
212 The output value, with its sign, must either be a positive value in
214 the range 1,2,...,OBJ2-1 or the same value subtracted OBJ2. For
215 instance, if the input arguments are objects representing the
216 numbers 7 and 5, the method must either return an object
217 representing the number 3 and a "+" sign, since (3*7) % 5 = 1 % 5,
218 or an object representing the number 2 and a "-" sign, since (-2*7)
219 % 5 = 1 % 5.
220 CLASS->_modpow(OBJ1, OBJ2, OBJ3)
222 Returns the modular exponentiation, i.e., (OBJ1 ** OBJ2) % OBJ3.
223 CLASS->_rsft(OBJ, N, B)
225 Returns the result after shifting OBJ N digits to thee right in
226 base B. This is equivalent to performing integer division by B**N
227 and discarding the remainder, except that it might be much faster.
228 For instance, if the object $obj represents the hexadecimal number
230 0xabcde, then "_rsft($obj, 2, 16)" returns an object representing
231 the number 0xabc. The "remainer", 0xde, is discarded and not
232 returned.
233 CLASS->_lsft(OBJ, N, B)
235 Returns the result after shifting OBJ N digits to the left in base
236 B. This is equivalent to multiplying by B**N, except that it might
237 be much faster.
238 CLASS->_log_int(OBJ, B)
240 Returns the logarithm of OBJ to base BASE truncted to an integer.
241 This method has two output arguments, the OBJECT and a STATUS. The
242 STATUS is Perl scalar; it is 1 if OBJ is the exact result, 0 if the
243 result was truncted to give OBJ, and undef if it is unknown whether
244 OBJ is the exact result.
245 CLASS->_gcd(OBJ1, OBJ2)
247 Returns the greatest common divisor of OBJ1 and OBJ2.
248 CLASS->_lcm(OBJ1, OBJ2)
250 Return the least common multiple of OBJ1 and OBJ2.
251 CLASS->_fib(OBJ)
253 In scalar context, returns the nth Fibonacci number: _fib(0)
254 returns 0, _fib(1) returns 1, _fib(2) returns 1, _fib(3) returns 2
255 etc. In list context, returns the Fibonacci numbers from F(0) to
256 F(n): 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, ...
257 CLASS->_lucas(OBJ)
259 In scalar context, returns the nth Lucas number: _lucas(0) returns
260 2, _lucas(1) returns 1, _lucas(2) returns 3, etc. In list context,
261 returns the Lucas numbers from L(0) to L(n): 2, 1, 3, 4, 7, 11, 18,
262 29,47, 76, ...
263 Bitwise operators
265 CLASS->_and(OBJ1, OBJ2)
267 Returns bitwise and.
268 CLASS->_or(OBJ1, OBJ2)
270 Returns bitwise or.
271 CLASS->_xor(OBJ1, OBJ2)
273 Returns bitwise exclusive or.
274 CLASS->_sand(OBJ1, OBJ2, SIGN1, SIGN2)
276 Returns bitwise signed and.
277 CLASS->_sor(OBJ1, OBJ2, SIGN1, SIGN2)
279 Returns bitwise signed or.
280 CLASS->_sxor(OBJ1, OBJ2, SIGN1, SIGN2)
282 Returns bitwise signed exclusive or.
283 Boolean operators
285 CLASS->_is_zero(OBJ)
287 Returns a true value if OBJ is zero, and false value otherwise.
288 CLASS->_is_one(OBJ)
290 Returns a true value if OBJ is one, and false value otherwise.
291 CLASS->_is_two(OBJ)
293 Returns a true value if OBJ is two, and false value otherwise.
294 CLASS->_is_ten(OBJ)
296 Returns a true value if OBJ is ten, and false value otherwise.
297 CLASS->_is_even(OBJ)
299 Return a true value if OBJ is an even integer, and a false value
300 otherwise.
301 CLASS->_is_odd(OBJ)
303 Return a true value if OBJ is an even integer, and a false value
304 otherwise.
305 CLASS->_acmp(OBJ1, OBJ2)
307 Compare OBJ1 and OBJ2 and return -1, 0, or 1, if OBJ1 is
308 numerically less than, equal to, or larger than OBJ2, respectively.
309 String conversion
311 CLASS->_str(OBJ)
313 Returns a string representing OBJ in decimal notation. The returned
314 string should have no leading zeros, i.e., it should match
315 "^(0|[1-9]\d*)$".
316 CLASS->_to_bin(OBJ)
318 Returns the binary string representation of OBJ.
319 CLASS->_to_oct(OBJ)
321 Returns the octal string representation of the number.
322 CLASS->_to_hex(OBJ)
324 Returns the hexadecimal string representation of the number.
325 CLASS->_to_bytes(OBJ)
327 Returns a byte string representation of OBJ. The byte string is in
328 big endian byte order, so if OBJ represents the number 256, the
329 output should be the two-byte string "\x01\x00".
330 CLASS->_to_base(OBJ, BASE, COLLSEQ)
332 Returns a string representation of OBJ in base BASE with collation
333 sequence COLLSEQ.
334 $val = $class -> _new("210");
336 $str = $class -> _to_base($val, 10, "xyz") # $str is "zyx"
337 $val = $class -> _new("32");
339 $str = $class -> _to_base($val, 2, "-|") # $str is "|-----"
340 See _from_base() for more information.
342 CLASS->_as_bin(OBJ)
344 Like "_to_bin()" but with a '0b' prefix.
345 CLASS->_as_oct(OBJ)
347 Like "_to_oct()" but with a '0' prefix.
348 CLASS->_as_hex(OBJ)
350 Like "_to_hex()" but with a '0x' prefix.
351 CLASS->_as_bytes(OBJ)
353 This is an alias to "_to_bytes()".
354 Numeric conversion
356 CLASS->_num(OBJ)
358 Returns a Perl scalar number representing the number OBJ as close
359 as possible. Since Perl scalars have limited precision, the
360 returned value might not be exactly the same as OBJ.
361 Miscellaneous
363 CLASS->_copy(OBJ)
365 Returns a true copy OBJ.
366 CLASS->_len(OBJ)
368 Returns the number of the decimal digits in OBJ. The output is a
369 Perl scalar.
370 CLASS->_zeros(OBJ)
372 Returns the number of trailing decimal zeros. The output is a Perl
373 scalar. The number zero has no trailing decimal zeros.
374 CLASS->_digit(OBJ, N)
376 Returns the Nth digit in OBJ as a Perl scalar. N is a Perl scalar,
377 where zero refers to the rightmost (least significant) digit, and
378 negative values count from the left (most significant digit). If
379 $obj represents the number 123, then
380 CLASS->_digit($obj, 0) # returns 3
382 CLASS->_digit($obj, 1) # returns 2
383 CLASS->_digit($obj, 2) # returns 1
384 CLASS->_digit($obj, -1) # returns 1
385 CLASS->_check(OBJ)
387 Returns true if the object is invalid and false otherwise.
388 Preferably, the true value is a string describing the problem with
389 the object. This is a check routine to test the internal state of
390 the object for corruption.
391 CLASS->_set(OBJ)
393 xxx
394 API version 2
396 The following methods are required for an API version of 2 or greater.
397 Constructors
399 CLASS->_1ex(N)
401 Return an object representing the number 10**N where N >= 0 is a
402 Perl scalar.
403 Mathematical functions
405 CLASS->_nok(OBJ1, OBJ2)
407 Return the binomial coefficient OBJ1 over OBJ1.
408 Miscellaneous
410 CLASS->_alen(OBJ)
412 Return the approximate number of decimal digits of the object. The
413 output is a Perl scalar.
414
416 If you want to port your own favourite C library for big numbers to the
417 Math::BigInt interface, you can take any of the already existing
418 modules as a rough guideline. You should really wrap up the latest
419 Math::BigInt and Math::BigFloat testsuites with your module, and
420 replace in them any of the following:
421 use Math::BigInt;
423 by this:
425 use Math::BigInt lib => 'yourlib';
427 This way you ensure that your library really works 100% within
429 Math::BigInt.
430
432 Please report any bugs or feature requests to "bug-math-bigint at
433 rt.cpan.org", or through the web interface at
434 <https://rt.cpan.org/Ticket/Create.html?Queue=Math-BigInt> (requires
435 login). We will be notified, and then you'll automatically be notified
436 of progress on your bug as I make changes.
437
439 You can find documentation for this module with the perldoc command.
440 perldoc Math::BigInt::Calc
442 You can also look for information at:
444 · RT: CPAN's request tracker
446 <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-BigInt>
448 · AnnoCPAN: Annotated CPAN documentation
450 <http://annocpan.org/dist/Math-BigInt>
452 · CPAN Ratings
454 <http://cpanratings.perl.org/dist/Math-BigInt>
456 · Search CPAN
458 <http://search.cpan.org/dist/Math-BigInt/>
460 · CPAN Testers Matrix
462 <http://matrix.cpantesters.org/?dist=Math-BigInt>
464 · The Bignum mailing list
466 · Post to mailing list
468 "bignum at lists.scsys.co.uk"
470 · View mailing list
472 <http://lists.scsys.co.uk/pipermail/bignum/>
474 · Subscribe/Unsubscribe
476 <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>
478
480 This program is free software; you may redistribute it and/or modify it
481 under the same terms as Perl itself.
482
484 Peter John Acklam, <pjacklam@online.no>
485 Code and documentation based on the Math::BigInt::Calc module by Tels
487 <nospam-abuse@bloodgate.com>
488
490 Math::BigInt, Math::BigInt::Calc, Math::BigInt::GMP,
491 Math::BigInt::FastCalc and Math::BigInt::Pari.
492perl v5.30.0 2019-07-26 Math::BigInt::Lib(3)