1Math::BigInt::Calc(3pm)Perl Programmers Reference GuideMath::BigInt::Calc(3pm)
2
3
4
6 Math::BigInt::Calc - Pure Perl module to support Math::BigInt
7
9 Provides support for big integer calculations. Not intended to be used
10 by other modules. Other modules which sport the same functions can also
11 be used to support Math::BigInt, like Math::BigInt::GMP or Math::Big‐
12 Int::Pari.
13
15 In order to allow for multiple big integer libraries, Math::BigInt was
16 rewritten to use library modules for core math routines. Any module
17 which follows the same API as this can be used instead by using the
18 following:
19
20 use Math::BigInt lib => 'libname';
21
22 'libname' is either the long name ('Math::BigInt::Pari'), or only the
23 short version like 'Pari'.
24
27 The following functions MUST be defined in order to support the use by
28 Math::BigInt v1.70 or later:
29
30 api_version() return API version, minimum 1 for v1.70
31 _new(string) return ref to new object from ref to decimal string
32 _zero() return a new object with value 0
33 _one() return a new object with value 1
34 _two() return a new object with value 2
35 _ten() return a new object with value 10
36
37 _str(obj) return ref to a string representing the object
38 _num(obj) returns a Perl integer/floating point number
39 NOTE: because of Perl numeric notation defaults,
40 the _num'ified obj may lose accuracy due to
41 machine-dependend floating point size limitations
42
43 _add(obj,obj) Simple addition of two objects
44 _mul(obj,obj) Multiplication of two objects
45 _div(obj,obj) Division of the 1st object by the 2nd
46 In list context, returns (result,remainder).
47 NOTE: this is integer math, so no
48 fractional part will be returned.
49 The second operand will be not be 0, so no need to
50 check for that.
51 _sub(obj,obj) Simple subtraction of 1 object from another
52 a third, optional parameter indicates that the params
53 are swapped. In this case, the first param needs to
54 be preserved, while you can destroy the second.
55 sub (x,y,1) => return x - y and keep x intact!
56 _dec(obj) decrement object by one (input is garant. to be > 0)
57 _inc(obj) increment object by one
58
59 _acmp(obj,obj) <=> operator for objects (return -1, 0 or 1)
60
61 _len(obj) returns count of the decimal digits of the object
62 _digit(obj,n) returns the n'th decimal digit of object
63
64 _is_one(obj) return true if argument is 1
65 _is_two(obj) return true if argument is 2
66 _is_ten(obj) return true if argument is 10
67 _is_zero(obj) return true if argument is 0
68 _is_even(obj) return true if argument is even (0,2,4,6..)
69 _is_odd(obj) return true if argument is odd (1,3,5,7..)
70
71 _copy return a ref to a true copy of the object
72
73 _check(obj) check whether internal representation is still intact
74 return 0 for ok, otherwise error message as string
75
76 _from_hex(str) return ref to new object from ref to hexadecimal string
77 _from_bin(str) return ref to new object from ref to binary string
78
79 _as_hex(str) return string containing the value as
80 unsigned hex string, with the '0x' prepended.
81 Leading zeros must be stripped.
82 _as_bin(str) Like as_hex, only as binary string containing only
83 zeros and ones. Leading zeros must be stripped and a
84 '0b' must be prepended.
85
86 _rsft(obj,N,B) shift object in base B by N 'digits' right
87 _lsft(obj,N,B) shift object in base B by N 'digits' left
88
89 _xor(obj1,obj2) XOR (bit-wise) object 1 with object 2
90 Note: XOR, AND and OR pad with zeros if size mismatches
91 _and(obj1,obj2) AND (bit-wise) object 1 with object 2
92 _or(obj1,obj2) OR (bit-wise) object 1 with object 2
93
94 _mod(obj,obj) Return remainder of div of the 1st by the 2nd object
95 _sqrt(obj) return the square root of object (truncated to int)
96 _root(obj) return the n'th (n >= 3) root of obj (truncated to int)
97 _fac(obj) return factorial of object 1 (1*2*3*4..)
98 _pow(obj,obj) return object 1 to the power of object 2
99 return undef for NaN
100 _zeros(obj) return number of trailing decimal zeros
101 _modinv return inverse modulus
102 _modpow return modulus of power ($x ** $y) % $z
103 _log_int(X,N) calculate integer log() of X in base N
104 X >= 0, N >= 0 (return undef for NaN)
105 returns (RESULT, EXACT) where EXACT is:
106 1 : result is exactly RESULT
107 0 : result was truncated to RESULT
108 undef : unknown whether result is exactly RESULT
109 _gcd(obj,obj) return Greatest Common Divisor of two objects
110
111 The following functions are optional, and can be defined if the under‐
112 lying lib has a fast way to do them. If undefined, Math::BigInt will
113 use pure Perl (hence slow) fallback routines to emulate these:
114
115 _signed_or
116 _signed_and
117 _signed_xor
118
119 Input strings come in as unsigned but with prefix (i.e. as '123',
120 '0xabc' or '0b1101').
121
122 So the library needs only to deal with unsigned big integers. Testing
123 of input parameter validity is done by the caller, so you need not
124 worry about underflow (f.i. in "_sub()", "_dec()") nor about division
125 by zero or similar cases.
126
127 The first parameter can be modified, that includes the possibility that
128 you return a reference to a completely different object instead.
129 Although keeping the reference and just changing it's contents is pref‐
130 ered over creating and returning a different reference.
131
132 Return values are always references to objects, strings, or true/false
133 for comparisation routines.
134
136 If you want to port your own favourite c-lib for big numbers to the
137 Math::BigInt interface, you can take any of the already existing mod‐
138 ules as a rough guideline. You should really wrap up the latest BigInt
139 and BigFloat testsuites with your module, and replace in them any of
140 the following:
141
142 use Math::BigInt;
143
144 by this:
145
146 use Math::BigInt lib => 'yourlib';
147
148 This way you ensure that your library really works 100% within
149 Math::BigInt.
150
152 This program is free software; you may redistribute it and/or modify it
153 under the same terms as Perl itself.
154
156 Original math code by Mark Biggar, rewritten by Tels <http://blood‐
157 gate.com/> in late 2000. Seperated from BigInt and shaped API with the
158 help of John Peacock.
159
160 Fixed, speed-up, streamlined and enhanced by Tels 2001 - 2005.
161
163 Math::BigInt, Math::BigFloat, Math::BigInt::BitVect, Math::BigInt::GMP,
164 Math::BigInt::FastCalc and Math::BigInt::Pari.
165
166
167
168perl v5.8.8 2001-09-21 Math::BigInt::Calc(3pm)