Gary Howland > Math-BigInteger-1.0 > BigInteger

Download:
Math-BigInteger-1.0.tar.gz

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Source  

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

syntax highlighting: