BigInteger(3)

NAME
BigInteger - Arbitrary length integer extension module for Perl

SYNOPSIS
 use Math::BigInteger;

DESCRIPTION
The BigInteger extension module gives access to Eric Young's bignum library. This provides a faster alternative to the Math::BigInt library.

The basic object in this library is a BigInteger. It is used to hold a single large integer.

It is not intended that this package be used directly, but instead be used by a wrapper package, such as the Math::BigInteger class.

FUNCTIONS
Many of the following functions can be used in two styles, by calling the function on an object, or by calling the function explicitly; for example, here are two ways of assigning to $a the sum of $b and $c:

        $a->add($b, $c);
or

        BigInteger::add($a, $b, $c);

  Creation/Destruction routines.

new
            my $bi = new BigInteger;        # Create a new BigInteger object.

clone
            my $b = $a->clone();

    Create a new BigInteger object from another BigInteger object.

copy
            copy($a, $b);

    Copy one BigInteger object to another.

save
            my $data = $bi->save();

    Save a BigInteger object as a MSB-first string.

restore
            my $bi = restore BigInteger $data;

    Create a new BigInteger object from a MSB-first string.

  Comparison functions

ucmp
            ucmp($a, $b);

    Return -1 if $a is less than $b, 0 if $a and $b are the same and 1 is $a is greater than $b. This is an unsigned comparison.

cmp
            cmp($a, $b);

    Return -1 if $a is less than $b, 0 if $a and $b are the same and 1 is $a is greater than $b. This is a signed comparison.

  Arithmetic Functions

inc $bi->inc();
    Increment $bi by one:

dec $bi->dec();
    Decrement $bi by one:

add
            $r->add($a, $b);

    Add $a and $b and return the result in $r.

mul
            $r->mul($a, $b);

    Multiply $a by $b and return the result in $r. Note that $r must not be the same object as $a or $b.

div
            div($dv, $rem, $m, $d);

    Divide $m by $d and return the result in $dv and the remainder in $rem. Either of $dv or $rem can be "undef", in which case that value is not returned.

mod
            $rem->mod($m, $d);

    Find the remainder of $m divided by $d and return it in $rem. This function is more efficient than "div".

lshift
            $r->lshift($a, $n);

    Shift $a left by $n bits.

lshift1
            $r->lshift1($a);

    Shift $a left by 1 bit. This form is more efficient than "lshift($r, $a, 1)".

rshift
            $r->rshift($a, $n);

    Shift $a right by $n bits.

rshift1
            $r->rshift1($a);

    Shift $a right by 1 bit. This form is more efficient than "rshift($r, $a, 1)".

mod_exp
            $r->mod_exp($a, $p, $mod);

    Raise $a to the $p power and return the remainder into $r when divided by $m.

modmul_recip
            modmul_recip($r, $x, $y, $m, $i, $nb);

    This function is used to perform an efficient "mod_mul" operation. If one is going to repeatedly perform "mod_mul" with the same modulus is worth calculating the reciprocal of the modulus and then using this function. This operation uses the fact that a/b == a*r where r is the reciprocal of b. On modern computers multiplication is very fast and big number division is very slow. $x is multiplied by $y and then divided by $m and the remainder is returned in $r. $i is the reciprocal of $m and $nb is the number of bits as returned from "reciprocal". This function is used in "mod_exp".

mul_mod
            $r->mul_mod($a, $b, $m);

    Multiply $a by $b and return the remainder into $r when divided by $m.

reciprical
            $r->reciprical($m);

    Return the reciprocal of $m into $r.

  Miscellaneous Routines

num_bits
            my $size = $bi->numbits();

    Return the size (in bits) of the BigInteger.

gcd
            $r->gcd($a, $b);

    $r has the greatest common divisor of $a and $b.

inverse_modn
            $r->inverse_modn($a, $n);

    This function creates a new BigInteger and returns it in $r. This number is the inverse mod $n of $a. By this it is meant that the returned value $r satisfies (a*r)%n == 1. This function is used in the generation of RSA keys.

BUGS
Negative numbers cannot be saved or restored. To fix this requires modification of Eric Young's library.

The documentation.

COPYRIGHT
Systemics Ltd ( http://www.systemics.com/ ).

Portions copyright Eric Young (eay@mincom.oz.au).