1Math::BigInt::Calc(3pm)Perl Programmers Reference GuideMath::BigInt::Calc(3pm)
2
6 Math::BigInt::Calc - Pure Perl module to support Math::BigInt
7
9 This library provides support for big integer calculations. It is not
10 intended to be used by other modules. Other modules which support the
11 same API (see below) can also be used to support Math::BigInt, like
12 Math::BigInt::GMP and Math::BigInt::Pari.
13
15 In this library, the numbers are represented in base B = 10**N, where N
16 is the largest possible value that does not cause overflow in the
17 intermediate computations. The base B elements are stored in an array,
18 with the least significant element stored in array element zero. There
19 are no leading zero elements, except a single zero element when the
20 number is zero.
21 For instance, if B = 10000, the number 1234567890 is represented
23 internally as [3456, 7890, 12].
24
26 In order to allow for multiple big integer libraries, Math::BigInt was
27 rewritten to use a plug-in library for core math routines. Any module
28 which conforms to the API can be used by Math::BigInt by using this in
29 your program:
30 use Math::BigInt lib => 'libname';
32 'libname' is either the long name, like 'Math::BigInt::Pari', or only
34 the short version, like 'Pari'.
35 General Notes
37 A library only needs to deal with unsigned big integers. Testing of
38 input parameter validity is done by the caller, so there is no need to
39 worry about underflow (e.g., in "_sub()" and "_dec()") nor about
40 division by zero (e.g., in "_div()") or similar cases.
41 For some methods, the first parameter can be modified. That includes
43 the possibility that you return a reference to a completely different
44 object instead. Although keeping the reference and just changing its
45 contents is preferred over creating and returning a different
46 reference.
47 Return values are always objects, strings, Perl scalars, or true/false
49 for comparison routines.
50 API version 1
52 The following methods must be defined in order to support the use by
53 Math::BigInt v1.70 or later.
54 API version
56 api_version()
58 Return API version as a Perl scalar, 1 for Math::BigInt v1.70, 2
59 for Math::BigInt v1.83.
60 Constructors
62 _new(STR)
64 Convert a string representing an unsigned decimal number to an
65 object representing the same number. The input is normalize, i.e.,
66 it matches "^(0|[1-9]\d*)$".
67 _zero()
69 Return an object representing the number zero.
70 _one()
72 Return an object representing the number one.
73 _two()
75 Return an object representing the number two.
76 _ten()
78 Return an object representing the number ten.
79 _from_bin(STR)
81 Return an object given a string representing a binary number. The
82 input has a '0b' prefix and matches the regular expression
83 "^0[bB](0|1[01]*)$".
84 _from_oct(STR)
86 Return an object given a string representing an octal number. The
87 input has a '0' prefix and matches the regular expression
88 "^0[1-7]*$".
89 _from_hex(STR)
91 Return an object given a string representing a hexadecimal number.
92 The input has a '0x' prefix and matches the regular expression
93 "^0x(0|[1-9a-fA-F][\da-fA-F]*)$".
94 Mathematical functions
96 Each of these methods may modify the first input argument, except
98 _bgcd(), which shall not modify any input argument, and _sub() which
99 may modify the second input argument.
100 _add(OBJ1, OBJ2)
102 Returns the result of adding OBJ2 to OBJ1.
103 _mul(OBJ1, OBJ2)
105 Returns the result of multiplying OBJ2 and OBJ1.
106 _div(OBJ1, OBJ2)
108 Returns the result of dividing OBJ1 by OBJ2 and truncating the
109 result to an integer.
110 _sub(OBJ1, OBJ2, FLAG)
112 _sub(OBJ1, OBJ2)
113 Returns the result of subtracting OBJ2 by OBJ1. If "flag" is false
114 or omitted, OBJ1 might be modified. If "flag" is true, OBJ2 might
115 be modified.
116 _dec(OBJ)
118 Decrement OBJ by one.
119 _inc(OBJ)
121 Increment OBJ by one.
122 _mod(OBJ1, OBJ2)
124 Return OBJ1 modulo OBJ2, i.e., the remainder after dividing OBJ1 by
125 OBJ2.
126 _sqrt(OBJ)
128 Return the square root of the object, truncated to integer.
129 _root(OBJ, N)
131 Return Nth root of the object, truncated to int. N is >= 3.
132 _fac(OBJ)
134 Return factorial of object (1*2*3*4*...).
135 _pow(OBJ1, OBJ2)
137 Return OBJ1 to the power of OBJ2. By convention, 0**0 = 1.
138 _modinv(OBJ1, OBJ2)
140 Return modular multiplicative inverse, i.e., return OBJ3 so that
141 (OBJ3 * OBJ1) % OBJ2 = 1 % OBJ2
143 The result is returned as two arguments. If the modular
145 multiplicative inverse does not exist, both arguments are
146 undefined. Otherwise, the arguments are a number (object) and its
147 sign ("+" or "-").
148 The output value, with its sign, must either be a positive value in
150 the range 1,2,...,OBJ2-1 or the same value subtracted OBJ2. For
151 instance, if the input arguments are objects representing the
152 numbers 7 and 5, the method must either return an object
153 representing the number 3 and a "+" sign, since (3*7) % 5 = 1 % 5,
154 or an object representing the number 2 and "-" sign, since (-2*7) %
155 5 = 1 % 5.
156 _modpow(OBJ1, OBJ2, OBJ3)
158 Return modular exponentiation, (OBJ1 ** OBJ2) % OBJ3.
159 _rsft(OBJ, N, B)
161 Shift object N digits right in base B and return the resulting
162 object. This is equivalent to performing integer division by B**N
163 and discarding the remainder, except that it might be much faster,
164 depending on how the number is represented internally.
165 For instance, if the object $obj represents the hexadecimal number
167 0xabcde, then "_rsft($obj, 2, 16)" returns an object representing
168 the number 0xabc. The "remainer", 0xde, is discarded and not
169 returned.
170 _lsft(OBJ, N, B)
172 Shift the object N digits left in base B. This is equivalent to
173 multiplying by B**N, except that it might be much faster, depending
174 on how the number is represented internally.
175 _log_int(OBJ, B)
177 Return integer log of OBJ to base BASE. This method has two output
178 arguments, the OBJECT and a STATUS. The STATUS is Perl scalar; it
179 is 1 if OBJ is the exact result, 0 if the result was truncted to
180 give OBJ, and undef if it is unknown whether OBJ is the exact
181 result.
182 _gcd(OBJ1, OBJ2)
184 Return the greatest common divisor of OBJ1 and OBJ2.
185 Bitwise operators
187 Each of these methods may modify the first input argument.
189 _and(OBJ1, OBJ2)
191 Return bitwise and. If necessary, the smallest number is padded
192 with leading zeros.
193 _or(OBJ1, OBJ2)
195 Return bitwise or. If necessary, the smallest number is padded with
196 leading zeros.
197 _xor(OBJ1, OBJ2)
199 Return bitwise exclusive or. If necessary, the smallest number is
200 padded with leading zeros.
201 Boolean operators
203 _is_zero(OBJ)
205 Returns a true value if OBJ is zero, and false value otherwise.
206 _is_one(OBJ)
208 Returns a true value if OBJ is one, and false value otherwise.
209 _is_two(OBJ)
211 Returns a true value if OBJ is two, and false value otherwise.
212 _is_ten(OBJ)
214 Returns a true value if OBJ is ten, and false value otherwise.
215 _is_even(OBJ)
217 Return a true value if OBJ is an even integer, and a false value
218 otherwise.
219 _is_odd(OBJ)
221 Return a true value if OBJ is an even integer, and a false value
222 otherwise.
223 _acmp(OBJ1, OBJ2)
225 Compare OBJ1 and OBJ2 and return -1, 0, or 1, if OBJ1 is less than,
226 equal to, or larger than OBJ2, respectively.
227 String conversion
229 _str(OBJ)
231 Return a string representing the object. The returned string should
232 have no leading zeros, i.e., it should match "^(0|[1-9]\d*)$".
233 _as_bin(OBJ)
235 Return the binary string representation of the number. The string
236 must have a '0b' prefix.
237 _as_oct(OBJ)
239 Return the octal string representation of the number. The string
240 must have a '0x' prefix.
241 Note: This method was required from Math::BigInt version 1.78, but
243 the required API version number was not incremented, so there are
244 older libraries that support API version 1, but do not support
245 "_as_oct()".
246 _as_hex(OBJ)
248 Return the hexadecimal string representation of the number. The
249 string must have a '0x' prefix.
250 Numeric conversion
252 _num(OBJ)
254 Given an object, return a Perl scalar number (int/float)
255 representing this number.
256 Miscellaneous
258 _copy(OBJ)
260 Return a true copy of the object.
261 _len(OBJ)
263 Returns the number of the decimal digits in the number. The output
264 is a Perl scalar.
265 _zeros(OBJ)
267 Return the number of trailing decimal zeros. The output is a Perl
268 scalar.
269 _digit(OBJ, N)
271 Return the Nth digit as a Perl scalar. N is a Perl scalar, where
272 zero refers to the rightmost (least significant) digit, and
273 negative values count from the left (most significant digit). If
274 $obj represents the number 123, then _digit($obj, 0) is 3 and
275 _digit(123, -1) is 1.
276 _check(OBJ)
278 Return a true value if the object is OK, and a false value
279 otherwise. This is a check routine to test the internal state of
280 the object for corruption.
281 API version 2
283 The following methods are required for an API version of 2 or greater.
284 Constructors
286 _1ex(N)
288 Return an object representing the number 10**N where N >= 0 is a
289 Perl scalar.
290 Mathematical functions
292 _nok(OBJ1, OBJ2)
294 Return the binomial coefficient OBJ1 over OBJ1.
295 Miscellaneous
297 _alen(OBJ)
299 Return the approximate number of decimal digits of the object. The
300 output is one Perl scalar. This estimate must be greater than or
301 equal to what "_len()" returns.
302 API optional methods
304 The following methods are optional, and can be defined if the
305 underlying lib has a fast way to do them. If undefined, Math::BigInt
306 will use pure Perl (hence slow) fallback routines to emulate these:
307 Signed bitwise operators.
309 Each of these methods may modify the first input argument.
311 _signed_or(OBJ1, OBJ2, SIGN1, SIGN2)
313 Return the signed bitwise or.
314 _signed_and(OBJ1, OBJ2, SIGN1, SIGN2)
316 Return the signed bitwise and.
317 _signed_xor(OBJ1, OBJ2, SIGN1, SIGN2)
319 Return the signed bitwise exclusive or.
320
322 If you want to port your own favourite c-lib for big numbers to the
323 Math::BigInt interface, you can take any of the already existing
324 modules as a rough guideline. You should really wrap up the latest
325 BigInt and BigFloat testsuites with your module, and replace in them
326 any of the following:
327 use Math::BigInt;
329 by this:
331 use Math::BigInt lib => 'yourlib';
333 This way you ensure that your library really works 100% within
335 Math::BigInt.
336
338 This program is free software; you may redistribute it and/or modify it
339 under the same terms as Perl itself.
340
342 · Original math code by Mark Biggar, rewritten by Tels
343 <http://bloodgate.com/> in late 2000.
344 · Separated from BigInt and shaped API with the help of John Peacock.
346 · Fixed, speed-up, streamlined and enhanced by Tels 2001 - 2007.
348 · API documentation corrected and extended by Peter John Acklam,
350 <pjacklam@online.no>
351
353 Math::BigInt, Math::BigFloat, Math::BigInt::GMP, Math::BigInt::FastCalc
354 and Math::BigInt::Pari.
355perl v5.16.3 2013-03-04 Math::BigInt::Calc(3pm)