NAME

Math::GMP - High speed arbitrary size integer math

VERSION

version 2.25

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.

$n->bnok($k)

$x = Math::GMP->new(5);
my $val = $x->bnok(2);      # 1*2*3*4*5/(1*2)/(1*2*3) = 10
print $val;

Calculates the binomial coefficient of $n over $k and returns the result. Equals to $n!/($k!*($n-$k)!).

( Added in version 2.23 .)

my $val = $x->band($y, $swap)

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

Calculates the bit-wise AND of its two arguments and returns the result. $swap should be provided but is ignored.

my $ret = $x->bxor($y, $swap);

$x = Math::GMP->new(6);
my $val = $x->bxor(3, 0);      # 0b110 ^ 0b11 = 0b101
print $val;

Calculates the bit-wise XOR of its two arguments and returns the result.

my $ret = $x->bior($y, $swap);

$x = Math::GMP->new(6);
my $val = $x->bior(3);      # 0b110 | 0b11 = 0b111
print $val;

Calculates the bit-wise OR of its two arguments and returns the result.

blshift

$x = Math::GMP->new(0b11);
my $result = $x->blshift(4, 0);
# $result = 0b11 << 4 = 0b110000

Calculates the bit-wise left-shift of its two arguments and returns the result. Second argument is swap.

brshift

$x = Math::GMP->new(0b11001);
my $result = $x->brshift(3, 0);
# $result = 0b11001 << 3 = 0b11

Calculates the bit-wise right-shift of its two arguments and returns the result. Second argument is swap.

bgcd

my $x = Math::GMP->new(6);
my $gcd = $x->bgcd(4);
# 6 / 2 = 3, 4 / 2 = 2 => 2
print $gcd

Returns the Greatest Common Divisor of the two arguments.

blcm

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

Returns the Least Common Multiple of the two arguments.

bmodinv

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

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.

broot

my $x = Math::GMP->new(100);
my $root = $x->root(3);    # int(100 ** (1/3)) => 4
print $root;

Returns the integer n'th root of its argument, given a positive integer n.

brootrem

my $x = Math::GMP->new(100);
my($root, $rem) = $x->rootrem(3); # 4 ** 3 + 36 = 100
print "$x is $rem more than the cube of $root";

Returns the integer n'th root of its argument, and the difference such that $root ** $n + $rem == $x .

bsqrt

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

Returns the integer square root of its argument.

bsqrtrem

my $x = Math::GMP->new(7);
my($root, $rem) = $x->sqrtrem(); # 2 ** 2 + 3 = 7
print "$x is $rem more than the square of $root";

Returns the integer square root of its argument, and the difference such that $root ** 2 + $rem == $x .

is_perfect_power

my $x = Math::GMP->new(100);
my $is_power = $x->is_perfect_power();
print "$x is " . ($is_power ? "" : "not ") . "a perfect power";

Returns TRUE if its argument is a power, ie if there exist integers a and b with b > 1 such that $x == $a ** $b .

is_perfect_square

my $x = Math::GMP->new(100);
my $is_square = $x->is_perfect_square();
print "$x is " . ($is_square ? "" : "not ") . "a perfect square";

Returns TRUE if its argument is the square of an integer.

legendre

$x = Math::GMP->new(6);
my $ret = $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

my $x = Math::GMP->new(6);
my $jacobi_verdict = $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

my $fib = Math::GMP::fibonacci(16);

Calculates the n'th number in the Fibonacci sequence.

probab_prime

my $x = Math::GMP->new(7);
my $is_prime_verdict = $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.

$x->add_ui_gmp($n)

Adds to $x and mutates it in-place. $n must be a regular non-GMP, positive, integer.

($quotient, $remainder) = $x->bdiv($y);

my $x = Math::GMP->new(7);
my ($quo, $rem) = $x->bdiv(3);

Returns both the division and the modulo of an integer division operation.

my $ret = $x->div_2exp_gmp($n);

my $x = Math::GMP->new(200);
my $ret = $x->div_2exp_gmp(2);

Returns a right-shift of the Math::GMP object by an unsigned regular integer. Also look at blshift() .

my $str = $x->get_str_gmp($base)

my $init_n = 3 * 7 + 2 * 7 * 7 + 6 * 7 * 7 * 7;
my $x = Math::GMP->new($init_n);
my $ret = $x->get_str_gmp(7);

print $ret; # Prints "6230".

Returns a string representation of the number in base $base.

my $clone = $x->gmp_copy()

Returns a copy of $x that can be modified without affecting the original.

my $verdict = $x->gmp_tstbit($bit_index);

Returns whether or not bit No. $bit_index is 1 in $x.

my $remainder = $dividend->mmod_gmp($divisor)

my $x = Math::GMP->new(2 . ('0' x 200) . 4);
my $y = Math::GMP->new(5);

my $ret = $x->mmod_gmp($y);
# $ret is now Math::GMP of 4.

From the GMP documentation:

Divide dividend and divisor and put the remainder in remainder. The remainder is always positive, and its value is less than the value of the divisor.

my $result = $x->mod_2exp_gmp($shift);

my $x = Math::GMP->new(0b10001011);
my $ret = $x->mod_2exp_gmp(4);

# $ret is now Math::GMP of 0b1011

Returns a Math::GMP object containing the lower $shift bits of $x (while not modifying $x).

my $left_shifted = $x->mul_2exp_gmp($shift);

my $x = Math::GMP->new(0b10001011);
my $ret = $x->mul_2exp_gmp(4);

# $ret is now Math::GMP of 0b1000_1011_0000

Returns a Math::GMP object containing $x shifted by $shift bits (where $shift is a plain integer).

my $multiplied = $x->bmulf($float)

my $x = Math::GMP->new(3)->bpow(100);
my $ret = $x->bmulf(1.5);

# $ret is now Math::GMP of floor(3^101 / 2)

Returns a Math::GMP object representing $x multiplied by the floating point value $float (with the result truncated towards zero).

( Added in version 2.23 .)

my $ret = $base->powm_gmp($exp, $mod);

my $base = Math::GMP->new(157);
my $exp = Math::GMP->new(100);
my $mod = Math::GMP->new(5013);

my $ret = $base->powm_gmp($exp, $mod);

# $ret is now (($base ** $exp) % $mod)

Returns $base raised to the power of $exp modulo $mod.

my $plain_int_ret = $x->sizeinbase_gmp($plain_int_base);

Returns the size of $x in base $plain_int_base .

my $int = $x->intify();

Returns the value of the object as an unblessed (and limited-in-precision) integer.

_gmp_build_version()

my $gmp_version = Math::GMP::_gmp_build_version;
if ($gmp_version ge 6.0.0) {
  print "Math::GMP was built against libgmp-6.0.0 or later";
}

Class method that returns as a vstring the version of libgmp against which this module was built.

_gmp_lib_version()

my $gmp_version = Math::GMP::_gmp_lib_version;
if ($gmp_version ge 6.0.0) {
  print "Math::GMP is now running with libgmp-6.0.0 or later";
}

Class method that returns as a vstring the version of libgmp it is currently running.

gcd()

An alias to bgcd() .