Math-BigInteger-1.0.tar.gz

Annotate this POD

 Open 0
View/Report Bugs

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

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:

`        \$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.