Math::BigInt::Calc(3pm)Perl Programmers Reference GuideMath::BigInt::Calc(3pm)
NAME
Math::BigInt::Calc - Pure Perl module to support Math::BigInt
SYNOPSIS
Provides support for big integer calculations. Not intended to be used
by other modules. Other modules which sport the same functions can also
be used to support Math::BigInt, like Math::BigInt::GMP or Math::Big-
Int::Pari.
DESCRIPTION
In order to allow for multiple big integer libraries, Math::BigInt was
rewritten to use library modules for core math routines. Any module
which follows the same API as this can be used instead by using the
following:
use Math::BigInt lib => 'libname';
'libname' is either the long name ('Math::BigInt::Pari'), or only the
short version like 'Pari'.
SSTTOORRAAGGEE
MMEETTHHOODDSS
The following functions MUST be defined in order to support the use by
Math::BigInt v1.70 or later:
apiversion() return API version, minimum 1 for v1.70
new(string) return ref to new object from ref to decimal string
zero() return a new object with value 0
one() return a new object with value 1
two() return a new object with value 2
ten() return a new object with value 10
str(obj) return ref to a string representing the object
num(obj) returns a Perl integer/floating point number
NOTE: because of Perl numeric notation defaults,
the num'ified obj may lose accuracy due to
machine-dependend floating point size limitations
add(obj,obj) Simple addition of two objects
mul(obj,obj) Multiplication of two objects
div(obj,obj) Division of the 1st object by the 2nd
In list context, returns (result,remainder).
NOTE: this is integer math, so no
fractional part will be returned.
The second operand will be not be 0, so no need to
check for that.
sub(obj,obj) Simple subtraction of 1 object from another
a third, optional parameter indicates that the params
are swapped. In this case, the first param needs to
be preserved, while you can destroy the second.
sub (x,y,1) => return x - y and keep x intact!
dec(obj) decrement object by one (input is garant. to be > 0)
inc(obj) increment object by one
acmp(obj,obj) <=> operator for objects (return -1, 0 or 1)
len(obj) returns count of the decimal digits of the object
digit(obj,n) returns the n'th decimal digit of object
isone(obj) return true if argument is 1
istwo(obj) return true if argument is 2
isten(obj) return true if argument is 10
iszero(obj) return true if argument is 0
iseven(obj) return true if argument is even (0,2,4,6..)
isodd(obj) return true if argument is odd (1,3,5,7..)
copy return a ref to a true copy of the object
check(obj) check whether internal representation is still intact
return 0 for ok, otherwise error message as string
fromhex(str) return ref to new object from ref to hexadecimal string
frombin(str) return ref to new object from ref to binary string
ashex(str) return string containing the value as
unsigned hex string, with the '0x' prepended.
Leading zeros must be stripped.
asbin(str) Like ashex, only as binary string containing only
zeros and ones. Leading zeros must be stripped and a
'0b' must be prepended.
rsft(obj,N,B) shift object in base B by N 'digits' right
lsft(obj,N,B) shift object in base B by N 'digits' left
xor(obj1,obj2) XOR (bit-wise) object 1 with object 2
Note: XOR, AND and OR pad with zeros if size mismatches
and(obj1,obj2) AND (bit-wise) object 1 with object 2
or(obj1,obj2) OR (bit-wise) object 1 with object 2
mod(obj,obj) Return remainder of div of the 1st by the 2nd object
sqrt(obj) return the square root of object (truncated to int)
root(obj) return the n'th (n >= 3) root of obj (truncated to int)
fac(obj) return factorial of object 1 (1*2*3*4..)
pow(obj,obj) return object 1 to the power of object 2
return undef for NaN
zeros(obj) return number of trailing decimal zeros
modinv return inverse modulus
modpow return modulus of power ($x ** $y) % $z
logint(X,N) calculate integer log() of X in base N
X >= 0, N >= 0 (return undef for NaN)
returns (RESULT, EXACT) where EXACT is:
1 : result is exactly RESULT
0 : result was truncated to RESULT
undef : unknown whether result is exactly RESULT
gcd(obj,obj) return Greatest Common Divisor of two objects
The following functions are optional, and can be defined if the under-
lying lib has a fast way to do them. If undefined, Math::BigInt will
use pure Perl (hence slow) fallback routines to emulate these:
signedor
signedand
signedxor
Input strings come in as unsigned but with prefix (i.e. as '123',
'0xabc' or '0b1101').
So the library needs only to deal with unsigned big integers. Testing
of input parameter validity is done by the caller, so you need not
worry about underflow (f.i. in "sub()", "dec()") nor about division
by zero or similar cases.
The first parameter can be modified, that includes the possibility that
you return a reference to a completely different object instead.
Although keeping the reference and just changing it's contents is pref-
ered over creating and returning a different reference.
Return values are always references to objects, strings, or true/false
for comparisation routines.
WWRRAAPP YYOOUURR OOWWNN
If you want to port your own favourite c-lib for big numbers to the
Math::BigInt interface, you can take any of the already existing mod-
ules as a rough guideline. You should really wrap up the latest BigInt
and BigFloat testsuites with your module, and replace in them any of
the following:
use Math::BigInt;
by this:
use Math::BigInt lib => 'yourlib';
This way you ensure that your library really works 100% within
Math::BigInt.
LLIICCEENNSSEE
This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
AUTHORS Original math code by Mark Biggar, rewritten by Tels gate.com/> in late 2000. Seperated from BigInt and shaped API with the
help of John Peacock.
Fixed, speed-up, streamlined and enhanced by Tels 2001 - 2005.
SEE ALSO
Math::BigInt, Math::BigFloat, Math::BigInt::BitVect, Math::BigInt::GMP,
Math::BigInt::FastCalc and Math::BigInt::Pari.
perl v5.8.8 2001-09-21 Math::BigInt::Calc(3pm)