1Math::BigInt::Calc(3pm)Perl Programmers Reference GuideMath::BigInt::Calc(3pm)
2
3
4

NAME

6       Math::BigInt::Calc - Pure Perl module to support Math::BigInt
7

SYNOPSIS

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

DESCRIPTION

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

STORAGE

METHODS

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, 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
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-dependent 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 guaranteed to be > 0)
57               _inc(obj)       increment object by one
58
59
60               _acmp(obj,obj)  <=> operator for objects (return -1, 0 or 1)
61
62               _len(obj)       returns count of the decimal digits of the object
63               _digit(obj,n)   returns the n'th decimal digit of object
64
65               _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
72               _copy           return a ref to a true copy of the object
73
74               _check(obj)     check whether internal representation is still intact
75                               return 0 for ok, otherwise error message as string
76
77               _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
81               _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
88               _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
91               _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
96               _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
113       The following functions are REQUIRED for an api_version of 2 or
114       greater:
115
116               _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
122       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
126               _signed_or
127               _signed_and
128               _signed_xor
129
130       Input strings come in as unsigned but with prefix (i.e. as '123',
131       '0xabc' or '0b1101').
132
133       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
138       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
143       Return values are always references to objects, strings, or true/false
144       for comparison routines.
145

WRAP YOUR OWN

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
153               use Math::BigInt;
154
155       by this:
156
157               use Math::BigInt lib => 'yourlib';
158
159       This way you ensure that your library really works 100% within
160       Math::BigInt.
161

LICENSE

163       This program is free software; you may redistribute it and/or modify it
164       under the same terms as Perl itself.
165

AUTHORS

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
171       Fixed, speed-up, streamlined and enhanced by Tels 2001 - 2007.
172

SEE ALSO

174       Math::BigInt, Math::BigFloat, Math::BigInt::GMP, Math::BigInt::FastCalc
175       and Math::BigInt::Pari.
176
177
178
179perl v5.12.4                      2011-06-20           Math::BigInt::Calc(3pm)
Impressum