Provided by: libmath-gmp-perl_2.25-1build4_amd64 bug

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

   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.

   op_add
       For internal use. Do not use directly.

   op_bool
       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_numify
       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_stringify
       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.

DIVISION BY ZERO

       Whereas perl normally catches division by zero to provide a standard perl-level error
       message, "libgmp" does not; the result is usually a SIGFPE (floating point exception)
       giving a core dump if you ever attempt to divide a "Math::GMP" object by anything that
       evaluates to zero. This can make it hard to diagnose where the error has occurred in your
       perl code.

       As of perl-5.36.0, SIGFPE is delivered in a way that can be caught by a %SIG handler. So
       you can get a stack trace with code like:

         use Carp;  # load it up front
         local $SIG{FPE} = sub { confess(@_) };

       Before perl-5.36.0 this approach won't work: you'll need to use "sigaction" in POSIX
       instead:

         use Carp;
         use POSIX qw{ sigaction SIGFPE };
         sigaction(SIGFPE, POSIX::SigAction->new(sub { confess(@_) }));

       In either case, you should not attempt to return from the signal handler, since the signal
       will just be thrown again.

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.

       See Math::GMPz, Math::GMPq, and friends ( <https://metacpan.org/search?q=math%3A%3Agmp> )
       for bindings of other parts of GMP / MPFR / etc.

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

       Shlomi Fish ( <https://www.shlomifish.org/> ) has done some maintenance work while putting
       his changes under CC0.

AUTHOR

       Shlomi Fish <shlomif@cpan.org>

COPYRIGHT AND LICENSE

       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 <mailto: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
       The following websites have more information about this module, and may be of help to you.
       As always, in addition to those websites please use your favorite search engine to
       discover more resources.

       •   MetaCPAN

           A modern, open-source CPAN search engine, useful to view POD in HTML format.

           <https://metacpan.org/release/Math-GMP>

       •   RT: CPAN's Bug Tracker

           The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.

           <https://rt.cpan.org/Public/Dist/Display.html?Name=Math-GMP>

       •   CPANTS

           The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.

           <http://cpants.cpanauthors.org/dist/Math-GMP>

       •   CPAN Testers

           The CPAN Testers is a network of smoke testers who run automated tests on uploaded
           CPAN distributions.

           <http://www.cpantesters.org/distro/M/Math-GMP>

       •   CPAN Testers Matrix

           The CPAN Testers Matrix is a website that provides a visual overview of the test
           results for a distribution on various Perls/platforms.

           <http://matrix.cpantesters.org/?dist=Math-GMP>

       •   CPAN Testers Dependencies

           The CPAN Testers Dependencies is a website that shows a chart of the test results of
           all dependencies for a distribution.

           <http://deps.cpantesters.org/?module=Math::GMP>

   Bugs / Feature Requests
       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.

   Source Code
       The code is open to the world, and available for you to hack on. Please feel free to
       browse it and play with it, or whatever. If you want to contribute patches, please send me
       a diff or prod me to pull from your repository :)

       <https://github.com/turnstep/Math-GMP>

         git clone https://github.com/turnstep/Math-GMP.git