unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-3.6)
Page:
Section:
Apropos / Subsearch:
optional field



Math::BigInt::CalPerl)Programmers ReferenceMath::BigInt::Calc(3p)


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'.

STORAGE
METHODS
       The following functions MUST be defined in order to sup-
       port the use by Math::BigInt v1.70 or later:

               api_version()   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


















perl v5.8.5                 2002-11-06                          1





Math::BigInt::CalPerl)Programmers ReferenceMath::BigInt::Calc(3p)


               _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

               _is_one(obj)    return true if argument is 1
               _is_two(obj)    return true if argument is 2
               _is_ten(obj)    return true if argument is 10
               _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 representation is still intact
                               return 0 for ok, otherwise error message as string

               _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 string containing 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 '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







perl v5.8.5                 2002-11-06                          2





Math::BigInt::CalPerl)Programmers ReferenceMath::BigInt::Calc(3p)


               _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
               _log_int(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 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:

               _signed_or
               _signed_and
               _signed_xor

       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 inte-
       gers. 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, strings,
       or true/false for comparisation routines.

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;




perl v5.8.5                 2002-11-06                          3





Math::BigInt::CalPerl)Programmers ReferenceMath::BigInt::Calc(3p)


       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.  Seperated from Big-
       Int and shaped API with the help of John Peacock.  Fixed,
       sped-up and enhanced by Tels http://bloodgate.com
       2001-2003.  Further streamlining (api_version 1) by Tels
       2004.

SEE ALSO
       Math::BigInt, Math::BigFloat, Math::BigInt::BitVect,
       Math::BigInt::GMP, Math::BigInt::FastCalc and Math::Big-
       Int::Pari.


































perl v5.8.5                 2002-11-06                          4