# NAME

Math::GMP - High speed arbitrary size integer math

# SYNOPSIS

```
use Math::GMP;
my $n = Math::GMP->new('2');
$n = $n ** (256*1024);
$n = $n - 1;
print "n is now $n\n";
```

# DESCRIPTION

Math::GMP was designed to be a drop-in replacement both for Math::BigInt and for regular integer arithmetic. Unlike BigInt, though, Math::GMP uses the GNU gmp library for all of its calculations, as opposed to straight Perl functions. This can result in speed improvements.

The downside is that this module requires a C compiler to install -- a small tradeoff in most cases. Also, this module is not 100% compatible with Math::BigInt.

A Math::GMP object can be used just as a normal numeric scalar would be -- the module overloads most of the normal arithmetic operators to provide as seamless an interface as possible. However, if you need a perfect interface, you can do the following:

```
use Math::GMP qw(:constant);
$n = 2 ** (256 * 1024);
print "n is $n\n";
```

This would fail without the ':constant' since Perl would use normal doubles to compute the 250,000 bit number, and thereby overflow it into meaninglessness (smaller exponents yield less accurate data due to floating point rounding).

# METHODS

Although the non-overload interface is not complete, the following functions do exist:

## new

` $x = Math::GMP->new(123);`

Creates a new Math::GMP object from the passed string or scalar.

` $x = Math::GMP->new('abcd', 36);`

Creates a new Math::GMP object from the first parameter which should be represented in the base specified by the second parameter.

## bfac

```
$x = Math::GMP->new(5);
my $val = $x->bfac(); # 1*2*3*4*5 = 120
print $val;
```

Calculates the factorial of $x and returns the result.

## band

```
$x = Math::GMP->new(6);
$x->band(3); # 0b110 & 0b11 = 1
```

Calculates the bit-wise AND of its two arguments and modifies the first argument.

## bxor

```
$x = Math::GMP->new(6);
$x->bxor(3); # 0b110 & 0b11 = 0b101
```

Calculates the bit-wise XOR of its two arguments and modifies the first argument.

## bior

```
$x = Math::GMP->new(6);
$x->bior(3); # 0b110 & 0b11 = 0b111
```

Calculates the bit-wise OR of its two arguments and modifies the first argument.

## bgcd

```
$x = Math::GMP->new(6);
$x->bgcd(4); # 6 / 2 = 2, 4 / 2 = 2 => 2
```

Returns the Greatest Common Divisor of the two arguments.

## blcm

```
$x = Math::GMP->new(6);
$x->blcm(4); # 6 * 2 = 12, 4 * 3 = 12 => 12
```

Returns the Least Common Multiple of the two arguments.

## bmodinv

```
$x = Math::GMP->new(5);
$x->bmodinv(7); # 5 * 3 == 1 (mod 7) => 3
```

Returns the modular inverse of $x (mod $y), if defined. This currently returns 0 if there is no inverse (but that may change in the future). Behaviour is undefined when $y is 0.

## bsqrt

```
$x = Math::GMP->new(6);
$x->bsqrt(); # int(sqrt(6)) => 2
```

Returns the integer square root of its argument.

## legendre

```
$x = Math::GMP->new(6);
$x->legendre(3);
```

Returns the value of the Legendre symbol ($x/$y). The value is defined only when $y is an odd prime; when the value is not defined, this currently returns 0 (but that may change in the future).

## jacobi

```
$x = Math::GMP->new(6);
$x->jacobi(3);
```

Returns the value of the Jacobi symbol ($x/$y). The value is defined only when $y is odd; when the value is not defined, this currently returns 0 (but that may change in the future).

## fibonacci

` $x = Math::GMP::fibonacci(16);`

Calculates the n'th number in the Fibonacci sequence.

## probab_prime

```
$x = Math::GMP->new(7);
$x->probab_prime(10);
```

Probabilistically determines if the number is a prime. Argument is the number of checks to perform. Returns 0 if the number is definitely not a prime, 1 if it may be, and 2 if it definitely is a prime.

# BUGS

As of version 1.0, Math::GMP is mostly compatible with the old Math::BigInt version. It is not a full replacement for the rewritten Math::BigInt versions, though. See the SEE ALSO section on how to achieve to use Math::GMP and retain full compatibility to Math::BigInt.

There are some slight incompatibilities, such as output of positive numbers not being prefixed by a '+' sign. This is intentional.

There are also some things missing, and not everything might work as expected.

# VERSION CONTROL

The version control repository of this module is a git repository hosted on GitHub at: https://github.com/turnstep/Math-GMP. Pull requests are welcome.

# SEE ALSO

Math::BigInt has a new interface to use a different library than the default pure Perl implementation. You can use, for instance, Math::GMP with it:

` use Math::BigInt lib => 'GMP';`

If Math::GMP is not installed, it will fall back to its own Perl implementation.

See Math::BigInt and Math::BigInt::GMP or Math::BigInt::Pari or Math::BigInt::BitVect.

# AUTHOR

Chip Turner <chip@redhat.com>, based on the old Math::BigInt by Mark Biggar and Ilya Zakharevich. Further extensive work provided by Tels <tels@bloodgate.com>.