Shlomi Fish > Math-GMP-2.15 > Math::GMP

Math-GMP-2.15.tar.gz

Dependencies

Annotate this POD

# CPAN RT

 Open 3
View/Report Bugs
Module Version: 2.15

# NAME

Math::GMP - High speed arbitrary size integer math

version 2.15

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

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

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 \$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() .

## lcm()

An alias to blcm() .

## constant

For internal use. Do not use directly.

## destroy

For internal use. Do not use directly.

## new_from_scalar

For internal use. Do not use directly.

## new_from_scalar_with_base

For internal use. Do not use directly.

For internal use. Do not use directly.

## op_div

For internal use. Do not use directly.

## op_eq

For internal use. Do not use directly.

## op_mod

For internal use. Do not use directly.

## op_mul

For internal use. Do not use directly.

## op_pow

For internal use. Do not use directly.

## op_spaceship

For internal use. Do not use directly.

## op_sub

For internal use. Do not use directly.

## stringify

For internal use. Do not use directly.

## uintify

For internal use. Do not use directly.

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

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.

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

# AUTHOR

Shlomi Fish <shlomif@cpan.org>

This software is Copyright (c) 2000 by James H. Turner.

This is free software, licensed under:

`  The GNU Lesser General Public License, Version 2.1, February 1999`

# BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Math-GMP or by email to bug-math-gmp@rt.cpan.org.

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

# SUPPORT

## Perldoc

You can find documentation for this module with the perldoc command.

`  perldoc Math::GMP`

## Websites

Please report any bugs or feature requests by email to `bug-math-gmp at rt.cpan.org`, or through the web interface at https://rt.cpan.org/Public/Bug/Report.html?Queue=Math-GMP. You will be automatically notified of any progress on the request by the system.
`  git clone https://github.com/turnstep/perl-Math-GMP.git`