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