.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Math::GMP 3pm" .TH Math::GMP 3pm "2020-11-08" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Math::GMP \- High speed arbitrary size integer math .SH "VERSION" .IX Header "VERSION" version 2.20 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Math::GMP; \& my $n = Math::GMP\->new(\*(Aq2\*(Aq); \& \& $n = $n ** (256*1024); \& $n = $n \- 1; \& print "n is now $n\en"; .Ve .SH "DESCRIPTION" .IX Header "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 \s-1GNU\s0 gmp library for all of its calculations, as opposed to straight Perl functions. This can result in speed improvements. .PP 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. .PP 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: .PP .Vb 1 \& use Math::GMP qw(:constant); \& \& $n = 2 ** (256 * 1024); \& print "n is $n\en"; .Ve .PP 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). .SH "METHODS" .IX Header "METHODS" Although the non-overload interface is not complete, the following functions do exist: .SS "new" .IX Subsection "new" .Vb 1 \& $x = Math::GMP\->new(123); .Ve .PP Creates a new Math::GMP object from the passed string or scalar. .PP .Vb 1 \& $x = Math::GMP\->new(\*(Aqabcd\*(Aq, 36); .Ve .PP Creates a new Math::GMP object from the first parameter which should be represented in the base specified by the second parameter. .SS "bfac" .IX Subsection "bfac" .Vb 3 \& $x = Math::GMP\->new(5); \& my $val = $x\->bfac(); # 1*2*3*4*5 = 120 \& print $val; .Ve .PP Calculates the factorial of \f(CW$x\fR and returns the result. .ie n .SS "my $val = $x\->band($y, $swap)" .el .SS "my \f(CW$val\fP = \f(CW$x\fP\->band($y, \f(CW$swap\fP)" .IX Subsection "my $val = $x->band($y, $swap)" .Vb 3 \& $x = Math::GMP\->new(6); \& my $val = $x\->band(3, 0); # 0b110 & 0b11 = 1 \& print $val; .Ve .PP Calculates the bit-wise \s-1AND\s0 of its two arguments and returns the result. \&\f(CW$swap\fR should be provided but is ignored. .ie n .SS "my $ret = $x\->bxor($y, $swap);" .el .SS "my \f(CW$ret\fP = \f(CW$x\fP\->bxor($y, \f(CW$swap\fP);" .IX Subsection "my $ret = $x->bxor($y, $swap);" .Vb 3 \& $x = Math::GMP\->new(6); \& my $val = $x\->bxor(3, 0); # 0b110 ^ 0b11 = 0b101 \& print $val; .Ve .PP Calculates the bit-wise \s-1XOR\s0 of its two arguments and returns the result. .ie n .SS "my $ret = $x\->bior($y, $swap);" .el .SS "my \f(CW$ret\fP = \f(CW$x\fP\->bior($y, \f(CW$swap\fP);" .IX Subsection "my $ret = $x->bior($y, $swap);" .Vb 3 \& $x = Math::GMP\->new(6); \& my $val = $x\->bior(3); # 0b110 | 0b11 = 0b111 \& print $val; .Ve .PP Calculates the bit-wise \s-1OR\s0 of its two arguments and returns the result. .SS "blshift" .IX Subsection "blshift" .Vb 3 \& $x = Math::GMP\->new(0b11); \& my $result = $x\->blshift(4, 0); \& # $result = 0b11 << 4 = 0b110000 .Ve .PP Calculates the bit-wise left-shift of its two arguments and returns the result. Second argument is swap. .SS "brshift" .IX Subsection "brshift" .Vb 3 \& $x = Math::GMP\->new(0b11001); \& my $result = $x\->brshift(3, 0); \& # $result = 0b11001 << 3 = 0b11 .Ve .PP Calculates the bit-wise right-shift of its two arguments and returns the result. Second argument is swap. .SS "bgcd" .IX Subsection "bgcd" .Vb 4 \& my $x = Math::GMP\->new(6); \& my $gcd = $x\->bgcd(4); \& # 6 / 2 = 3, 4 / 2 = 2 => 2 \& print $gcd .Ve .PP Returns the Greatest Common Divisor of the two arguments. .SS "blcm" .IX Subsection "blcm" .Vb 3 \& my $x = Math::GMP\->new(6); \& my $lcm = $x\->blcm(4); # 6 * 2 = 12, 4 * 3 = 12 => 12 \& print $lcm; .Ve .PP Returns the Least Common Multiple of the two arguments. .SS "bmodinv" .IX Subsection "bmodinv" .Vb 3 \& my $x = Math::GMP\->new(5); \& my $modinv = $x\->bmodinv(7); # 5 * 3 == 1 (mod 7) => 3 \& print $modinv; .Ve .PP Returns the modular inverse of \f(CW$x\fR (mod \f(CW$y\fR), if defined. This currently returns 0 if there is no inverse (but that may change in the future). Behaviour is undefined when \f(CW$y\fR is 0. .SS "broot" .IX Subsection "broot" .Vb 3 \& my $x = Math::GMP\->new(100); \& my $root = $x\->root(3); # int(100 ** (1/3)) => 4 \& print $root; .Ve .PP Returns the integer n'th root of its argument, given a positive integer n. .SS "brootrem" .IX Subsection "brootrem" .Vb 3 \& 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"; .Ve .PP Returns the integer n'th root of its argument, and the difference such that \&\f(CW\*(C` $root ** $n + $rem == $x \*(C'\fR. .SS "bsqrt" .IX Subsection "bsqrt" .Vb 3 \& my $x = Math::GMP\->new(6); \& my $root = $x\->bsqrt(); # int(sqrt(6)) => 2 \& print $root; .Ve .PP Returns the integer square root of its argument. .SS "bsqrtrem" .IX Subsection "bsqrtrem" .Vb 3 \& 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"; .Ve .PP Returns the integer square root of its argument, and the difference such that \&\f(CW\*(C` $root ** 2 + $rem == $x \*(C'\fR. .SS "is_perfect_power" .IX Subsection "is_perfect_power" .Vb 3 \& my $x = Math::GMP\->new(100); \& my $is_power = $x\->is_perfect_power(); \& print "$x is " . ($is_power ? "" : "not ") . "a perfect power"; .Ve .PP Returns \f(CW\*(C`TRUE\*(C'\fR if its argument is a power, ie if there exist integers a and b with b > 1 such that \f(CW\*(C` $x == $a ** $b \*(C'\fR. .SS "is_perfect_square" .IX Subsection "is_perfect_square" .Vb 3 \& my $x = Math::GMP\->new(100); \& my $is_square = $x\->is_perfect_square(); \& print "$x is " . ($is_square ? "" : "not ") . "a perfect square"; .Ve .PP Returns \f(CW\*(C`TRUE\*(C'\fR if its argument is the square of an integer. .SS "legendre" .IX Subsection "legendre" .Vb 2 \& $x = Math::GMP\->new(6); \& my $ret = $x\->legendre(3); .Ve .PP Returns the value of the Legendre symbol ($x/$y). The value is defined only when \f(CW$y\fR is an odd prime; when the value is not defined, this currently returns 0 (but that may change in the future). .SS "jacobi" .IX Subsection "jacobi" .Vb 2 \& my $x = Math::GMP\->new(6); \& my $jacobi_verdict = $x\->jacobi(3); .Ve .PP Returns the value of the Jacobi symbol ($x/$y). The value is defined only when \f(CW$y\fR is odd; when the value is not defined, this currently returns 0 (but that may change in the future). .SS "fibonacci" .IX Subsection "fibonacci" .Vb 1 \& my $fib = Math::GMP::fibonacci(16); .Ve .PP Calculates the n'th number in the Fibonacci sequence. .SS "probab_prime" .IX Subsection "probab_prime" .Vb 2 \& my $x = Math::GMP\->new(7); \& my $is_prime_verdict = $x\->probab_prime(10); .Ve .PP 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. .ie n .SS "$x\->add_ui_gmp($n)" .el .SS "\f(CW$x\fP\->add_ui_gmp($n)" .IX Subsection "$x->add_ui_gmp($n)" Adds to \f(CW$x\fR and mutates it in-place. \f(CW$n\fR must be a regular non-GMP, positive, integer. .ie n .SS "($quotient, $remainder) = $x\->bdiv($y);" .el .SS "($quotient, \f(CW$remainder\fP) = \f(CW$x\fP\->bdiv($y);" .IX Subsection "($quotient, $remainder) = $x->bdiv($y);" .Vb 2 \& my $x = Math::GMP\->new(7); \& my ($quo, $rem) = $x\->bdiv(3); .Ve .PP Returns both the division and the modulo of an integer division operation. .ie n .SS "my $ret = $x\->div_2exp_gmp($n);" .el .SS "my \f(CW$ret\fP = \f(CW$x\fP\->div_2exp_gmp($n);" .IX Subsection "my $ret = $x->div_2exp_gmp($n);" .Vb 2 \& my $x = Math::GMP\->new(200); \& my $ret = $x\->div_2exp_gmp(2); .Ve .PP Returns a right-shift of the Math::GMP object by an unsigned regular integer. Also look at \fBblshift()\fR . .ie n .SS "my $str = $x\->get_str_gmp($base)" .el .SS "my \f(CW$str\fP = \f(CW$x\fP\->get_str_gmp($base)" .IX Subsection "my $str = $x->get_str_gmp($base)" .Vb 3 \& 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". .Ve .PP Returns a string representation of the number in base \f(CW$base\fR. .ie n .SS "my $clone = $x\->\fBgmp_copy()\fP" .el .SS "my \f(CW$clone\fP = \f(CW$x\fP\->\fBgmp_copy()\fP" .IX Subsection "my $clone = $x->gmp_copy()" Returns a copy of \f(CW$x\fR that can be modified without affecting the original. .ie n .SS "my $verdict = $x\->gmp_tstbit($bit_index);" .el .SS "my \f(CW$verdict\fP = \f(CW$x\fP\->gmp_tstbit($bit_index);" .IX Subsection "my $verdict = $x->gmp_tstbit($bit_index);" Returns whether or not bit No. \f(CW$bit_index\fR is 1 in \f(CW$x\fR. .ie n .SS "my $remainder = $dividend\->mmod_gmp($divisor)" .el .SS "my \f(CW$remainder\fP = \f(CW$dividend\fP\->mmod_gmp($divisor)" .IX Subsection "my $remainder = $dividend->mmod_gmp($divisor)" .Vb 2 \& my $x = Math::GMP\->new(2 . (\*(Aq0\*(Aq x 200) . 4); \& my $y = Math::GMP\->new(5); \& \& my $ret = $x\->mmod_gmp($y); \& # $ret is now Math::GMP of 4. .Ve .PP From the \s-1GMP\s0 documentation: .PP 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. .ie n .SS "my $result = $x\->mod_2exp_gmp($shift);" .el .SS "my \f(CW$result\fP = \f(CW$x\fP\->mod_2exp_gmp($shift);" .IX Subsection "my $result = $x->mod_2exp_gmp($shift);" .Vb 2 \& my $x = Math::GMP\->new(0b10001011); \& my $ret = $x\->mod_2exp_gmp(4); \& \& # $ret is now Math::GMP of 0b1011 .Ve .PP Returns a Math::GMP object containing the lower \f(CW$shift\fR bits of \f(CW$x\fR (while not modifying \f(CW$x\fR). .ie n .SS "my $left_shifted = $x\->mul_2exp_gmp($shift);" .el .SS "my \f(CW$left_shifted\fP = \f(CW$x\fP\->mul_2exp_gmp($shift);" .IX Subsection "my $left_shifted = $x->mul_2exp_gmp($shift);" .Vb 2 \& my $x = Math::GMP\->new(0b10001011); \& my $ret = $x\->mul_2exp_gmp(4); \& \& # $ret is now Math::GMP of 0b1000_1011_0000 .Ve .PP Returns a Math::GMP object containing \f(CW$x\fR shifted by \f(CW$shift\fR bits (where \f(CW$shift\fR is a plain integer). .ie n .SS "my $ret = $base\->powm_gmp($exp, $mod);" .el .SS "my \f(CW$ret\fP = \f(CW$base\fP\->powm_gmp($exp, \f(CW$mod\fP);" .IX Subsection "my $ret = $base->powm_gmp($exp, $mod);" .Vb 3 \& 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) .Ve .PP Returns \f(CW$base\fR raised to the power of \f(CW$exp\fR modulo \f(CW$mod\fR. .ie n .SS "my $plain_int_ret = $x\->sizeinbase_gmp($plain_int_base);" .el .SS "my \f(CW$plain_int_ret\fP = \f(CW$x\fP\->sizeinbase_gmp($plain_int_base);" .IX Subsection "my $plain_int_ret = $x->sizeinbase_gmp($plain_int_base);" Returns the size of \f(CW$x\fR in base \f(CW$plain_int_base\fR . .ie n .SS "my $int = $x\->\fBintify()\fP;" .el .SS "my \f(CW$int\fP = \f(CW$x\fP\->\fBintify()\fP;" .IX Subsection "my $int = $x->intify();" Returns the value of the object as an unblessed (and limited-in-precision) integer. .SS "\fB_gmp_build_version()\fP" .IX Subsection "_gmp_build_version()" .Vb 4 \& 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"; \& } .Ve .PP Class method that returns as a vstring the version of libgmp against which this module was built. .SS "\fB_gmp_lib_version()\fP" .IX Subsection "_gmp_lib_version()" .Vb 4 \& 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"; \& } .Ve .PP Class method that returns as a vstring the version of libgmp it is currently running. .SS "\fBgcd()\fP" .IX Subsection "gcd()" An alias to \fBbgcd()\fR . .SS "\fBlcm()\fP" .IX Subsection "lcm()" An alias to \fBblcm()\fR . .SS "constant" .IX Subsection "constant" For internal use. \fBDo not use directly\fR. .SS "destroy" .IX Subsection "destroy" For internal use. \fBDo not use directly\fR. .SS "new_from_scalar" .IX Subsection "new_from_scalar" For internal use. \fBDo not use directly\fR. .SS "new_from_scalar_with_base" .IX Subsection "new_from_scalar_with_base" For internal use. \fBDo not use directly\fR. .SS "op_add" .IX Subsection "op_add" For internal use. \fBDo not use directly\fR. .SS "op_div" .IX Subsection "op_div" For internal use. \fBDo not use directly\fR. .SS "op_eq" .IX Subsection "op_eq" For internal use. \fBDo not use directly\fR. .SS "op_mod" .IX Subsection "op_mod" For internal use. \fBDo not use directly\fR. .SS "op_mul" .IX Subsection "op_mul" For internal use. \fBDo not use directly\fR. .SS "op_pow" .IX Subsection "op_pow" For internal use. \fBDo not use directly\fR. .SS "op_spaceship" .IX Subsection "op_spaceship" For internal use. \fBDo not use directly\fR. .SS "op_sub" .IX Subsection "op_sub" For internal use. \fBDo not use directly\fR. .SS "stringify" .IX Subsection "stringify" For internal use. \fBDo not use directly\fR. .SS "uintify" .IX Subsection "uintify" For internal use. \fBDo not use directly\fR. .SH "BUGS" .IX Header "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 \s-1SEE ALSO\s0 section on how to achieve to use Math::GMP and retain full compatibility to Math::BigInt. .PP There are some slight incompatibilities, such as output of positive numbers not being prefixed by a '+' sign. This is intentional. .PP There are also some things missing, and not everything might work as expected. .SH "VERSION CONTROL" .IX Header "VERSION CONTROL" The version control repository of this module is a git repository hosted on GitHub at: . Pull requests are welcome. .SH "SEE ALSO" .IX Header "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: .PP .Vb 1 \& use Math::BigInt lib => \*(AqGMP\*(Aq; .Ve .PP If Math::GMP is not installed, it will fall back to its own Perl implementation. .PP See Math::BigInt and Math::BigInt::GMP or Math::BigInt::Pari or Math::BigInt::BitVect. .SH "AUTHOR" .IX Header "AUTHOR" Chip Turner , based on the old Math::BigInt by Mark Biggar and Ilya Zakharevich. Further extensive work provided by Tels . .SH "AUTHOR" .IX Header "AUTHOR" Shlomi Fish .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2000 by James H. Turner. .PP This is free software, licensed under: .PP .Vb 1 \& The GNU Lesser General Public License, Version 2.1, February 1999 .Ve .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests on the bugtracker website or by email to bug\-math\-gmp@rt.cpan.org . .PP 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. .SH "SUPPORT" .IX Header "SUPPORT" .SS "Perldoc" .IX Subsection "Perldoc" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Math::GMP .Ve .SS "Websites" .IX Subsection "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. .IP "\(bu" 4 MetaCPAN .Sp A modern, open-source \s-1CPAN\s0 search engine, useful to view \s-1POD\s0 in \s-1HTML\s0 format. .Sp .IP "\(bu" 4 \&\s-1RT: CPAN\s0's Bug Tracker .Sp The \s-1RT\s0 ( Request Tracker ) website is the default bug/issue tracking system for \s-1CPAN.\s0 .Sp .IP "\(bu" 4 \&\s-1CPANTS\s0 .Sp The \s-1CPANTS\s0 is a website that analyzes the Kwalitee ( code metrics ) of a distribution. .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Testers .Sp The \s-1CPAN\s0 Testers is a network of smoke testers who run automated tests on uploaded \s-1CPAN\s0 distributions. .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Testers Matrix .Sp The \s-1CPAN\s0 Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms. .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Testers Dependencies .Sp The \s-1CPAN\s0 Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution. .Sp .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests by email to \f(CW\*(C`bug\-math\-gmp at rt.cpan.org\*(C'\fR, or through the web interface at . You will be automatically notified of any progress on the request by the system. .SS "Source Code" .IX Subsection "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 :) .PP .PP .Vb 1 \& git clone https://github.com/turnstep/Math\-GMP.git .Ve