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 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
12 Math::BigInt::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 use Math::BigInt lib => 'libname';
21 '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 api_version() return API version, 1 for v1.70, 2 for v1.83
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 _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-dependent floating point size limitations
42 _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 guaranteed to be > 0)
57 _inc(obj) increment object by one
58 _acmp(obj,obj) <=> operator for objects (return -1, 0 or 1)
61 _len(obj) returns count of the decimal digits of the object
63 _digit(obj,n) returns the n'th decimal digit of object
64 _is_one(obj) return true if argument is 1
66 _is_two(obj) return true if argument is 2
67 _is_ten(obj) return true if argument is 10
68 _is_zero(obj) return true if argument is 0
69 _is_even(obj) return true if argument is even (0,2,4,6..)
70 _is_odd(obj) return true if argument is odd (1,3,5,7..)
71 _copy return a ref to a true copy of the object
73 _check(obj) check whether internal representation is still intact
75 return 0 for ok, otherwise error message as string
76 _from_hex(str) return new object from a hexadecimal string
78 _from_bin(str) return new object from a binary string
79 _from_oct(str) return new object from an octal string
80 _as_hex(str) return string containing the value as
82 unsigned hex string, with the '0x' prepended.
83 Leading zeros must be stripped.
84 _as_bin(str) Like as_hex, only as binary string containing only
85 zeros and ones. Leading zeros must be stripped and a
86 '0b' must be prepended.
87 _rsft(obj,N,B) shift object in base B by N 'digits' right
89 _lsft(obj,N,B) shift object in base B by N 'digits' left
90 _xor(obj1,obj2) XOR (bit-wise) object 1 with object 2
92 Note: XOR, AND and OR pad with zeros if size mismatches
93 _and(obj1,obj2) AND (bit-wise) object 1 with object 2
94 _or(obj1,obj2) OR (bit-wise) object 1 with object 2
95 _mod(obj1,obj2) Return remainder of div of the 1st by the 2nd object
97 _sqrt(obj) return the square root of object (truncated to int)
98 _root(obj) return the n'th (n >= 3) root of obj (truncated to int)
99 _fac(obj) return factorial of object 1 (1*2*3*4..)
100 _pow(obj1,obj2) return object 1 to the power of object 2
101 return undef for NaN
102 _zeros(obj) return number of trailing decimal zeros
103 _modinv return inverse modulus
104 _modpow return modulus of power ($x ** $y) % $z
105 _log_int(X,N) calculate integer log() of X in base N
106 X >= 0, N >= 0 (return undef for NaN)
107 returns (RESULT, EXACT) where EXACT is:
108 1 : result is exactly RESULT
109 0 : result was truncated to RESULT
110 undef : unknown whether result is exactly RESULT
111 _gcd(obj,obj) return Greatest Common Divisor of two objects
112 The following functions are REQUIRED for an api_version of 2 or
114 greater:
115 _1ex($x) create the number 1Ex where x >= 0
117 _alen(obj) returns approximate count of the decimal digits of the
118 object. This estimate MUST always be greater or equal
119 to what _len() returns.
120 _nok(n,k) calculate n over k (binomial coefficient)
121 The following functions are optional, and can be defined if the
123 underlying lib has a fast way to do them. If undefined, Math::BigInt
124 will use pure Perl (hence slow) fallback routines to emulate these:
125 _signed_or
127 _signed_and
128 _signed_xor
129 Input strings come in as unsigned but with prefix (i.e. as '123',
131 '0xabc' or '0b1101').
132 So the library needs only to deal with unsigned big integers. Testing
134 of input parameter validity is done by the caller, so you need not
135 worry about underflow (f.i. in "_sub()", "_dec()") nor about division
136 by zero or similar cases.
137 The first parameter can be modified, that includes the possibility that
139 you return a reference to a completely different object instead.
140 Although keeping the reference and just changing its contents is
141 preferred over creating and returning a different reference.
142 Return values are always references to objects, strings, or true/false
144 for comparison routines.
145
147 If you want to port your own favourite c-lib for big numbers to the
148 Math::BigInt interface, you can take any of the already existing
149 modules as a rough guideline. You should really wrap up the latest
150 BigInt and BigFloat testsuites with your module, and replace in them
151 any of the following:
152 use Math::BigInt;
154 by this:
156 use Math::BigInt lib => 'yourlib';
158 This way you ensure that your library really works 100% within
160 Math::BigInt.
161
163 This program is free software; you may redistribute it and/or modify it
164 under the same terms as Perl itself.
165
167 Original math code by Mark Biggar, rewritten by Tels
168 <http://bloodgate.com/> in late 2000. Seperated from BigInt and shaped
169 API with the help of John Peacock.
170 Fixed, speed-up, streamlined and enhanced by Tels 2001 - 2007.
172
174 Math::BigInt, Math::BigFloat, Math::BigInt::GMP, Math::BigInt::FastCalc
175 and Math::BigInt::Pari.
176perl v5.12.4 2011-06-20 Math::BigInt::Calc(3pm)