math::bigint::calc(3)

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 (except Math::Big
Int::Cached). Other modules which sport the same functions
can also be used to support Math::Bigint, like 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'.

EXPORT

The following functions MUST be defined in order to sup port the use by Math::BigInt:: _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; _str(obj) return ref to a string represent; ing the object
_num(obj) returns a Perl integer/floating; point number
NOTE: because of Perl numeric no

tation defaults,
the _num'ified obj may lose accu

racy 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 (re; sult,remainder).
NOTE: this is integer math, so no
fractional part will be returned.
_sub(obj,obj) Simple subtraction of 1 object
from another: a third, optional parameter indi; cates that the params
are swapped. In this case, the; first param needs to
be preserved, while you can de; stroy 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 dig
its of the object _digit(obj,n) returns the n'th decimal digit of
object
_is_one(obj) return true if argument is +1 _is_zero(obj) return true if argument is 0 _is_even(obj) return true if argument is even
(0,2,4,6..) _is_odd(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 representa
tion is still intact: return 0 for ok, otherwise error; message as string
The following functions are optional, and can be defined if the underlying lib has a fast way to do them. If unde fined, Math::BigInt will use pure Perl (hence slow) fall back routines to emulate these:: _from_hex(str) return ref to new object from ref; to hexadecimal string
_from_bin(str) return ref to new object from ref; to binary string; _as_hex(str) return ref to scalar string con; taining the value as
unsigned hex string, with the '0x'

prepended.
Leading zeros must be stripped.; _as_bin(str) Like as_hex, 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 'dig
its' right: For unsupported bases B, return; undef to signal failure
_lsft(obj,N,B) shift object in base B by N 'dig
its' left: For unsupported bases B, return; undef to signal failure
_xor(obj1,obj2) XOR (bit-wise) object 1 with ob
ject 2: Note: XOR, AND and OR pad with ze; ros if size mismatches
_and(obj1,obj2) AND (bit-wise) object 1 with ob
ject 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
(truncate 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 _gcd(obj,obj) return Greatest Common Divisor of
two objects
_zeros(obj) return number of trailing decimal
zeros
_modinv return inverse modulus
_modpow return modulus of power ($x ** $y)
% $z
Input strings come in as unsigned but with prefix (i.e. as '123', '0xabc' or '0b1101').
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 prefered over creating and returning a different reference.
Return values are always references to objects or strings. Exceptions are "_lsft()" and "_rsft()", which return undef if they can not shift the argument. This is used to dele gate shifting of bases different than the one you can sup port back to Math::BigInt, which will use some generic code to calculate the result.

WRAP YOUR OWN

If you want to port your own favourite c-lib for big num bers to the Math::BigInt interface, you can take any of the already existing modules as a rough guideline. You should really wrap up the latest BigInt and BigFloat test suites 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.

LICENSE

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
<http://bloodgate.com/> in late 2000, 2001. Seperated
from BigInt and shaped API with the help of John Peacock.

docs.sk

comprehensive documentation repository

In section