Math::GMP#
Arbitrary-precision integer arithmetic backed by GNU libgmp.
Math::GMP lets you work with integers of unlimited size. The
interpreter’s native integer tops out somewhere around 2**63;
pass anything bigger through a Math::GMP object and every
arithmetic operator keeps working, up to the memory you have.
Build a value with Math::GMP->new, then use it like a normal
number — the module overloads + - * / % ** <=> == & | ^ << >>
so $x * $y and $x ** 1000 Do The Right Thing. Only the final
stringification crosses back into ordinary Perl:
use Math::GMP;
my $x = Math::GMP->new('2');
my $huge = $x ** 1024; # a 309-digit integer
print "$huge\n";
A Math::GMP value is a blessed reference whose underlying scalar
holds a pointer to a GMP mpz_t. Passing one to ref returns
"Math::GMP"; passing it to a stringifying or numifying operator
goes through the overloaded op_stringify / op_numify.
The :constant pragma extends the overloading to bare integer
literals in your source:
use Math::GMP qw(:constant);
my $n = 2 ** (256 * 1024); # evaluated in GMP, not doubles
Without :constant the exponent 256 * 1024 would be computed as
a C double and overflow to infinity before Math::GMP ever sees it.
Division by zero#
libgmp raises SIGFPE on division by zero instead of returning a
Perl-level error. On Perl 5.36 and later you can trap it with a
$SIG{FPE} handler; on older Perls use POSIX::sigaction.
Returning from the handler re-raises the signal, so use it for
diagnostics (Carp::confess) rather than recovery.
Functions#
Construction#
const_integer#
Wrap an integer literal in a Math::GMP object.
new_from_scalar#
Build a Math::GMP object from a decimal/auto-detected string.
new_from_scalar_with_base#
Build a Math::GMP object from a string in the given base.
destroy#
Release the mpz_t backing a Math::GMP object.
gmp_copy#
Return an independent copy of $x.
Conversion#
stringify#
Return the decimal string representation of a Math::GMP value.
get_str_gmp#
Return the string representation of $x in the given base.
sizeinbase_gmp#
Return the number of digits $x would take in the given base.
uintify#
Return the low bits of $x as a plain unsigned Perl integer.
intify#
Return $x as a plain signed Perl integer.
Arithmetic#
add_ui_gmp#
Add an unsigned integer to $x in place.
op_add#
Overloaded + — return $m + $n as a new Math::GMP.
op_sub#
Overloaded - — return $m - $n as a new Math::GMP.
op_mul#
Overloaded * — return $m * $n as a new Math::GMP.
bmulf#
Return $x multiplied by a floating-point value, truncated to an integer.
op_div#
Overloaded / — integer division int($m / $n), truncated toward zero.
bdiv#
Return the quotient and remainder of $m / $n as a two-element list.
op_mod#
Overloaded % — remainder of $m / $n, sign follows the dividend.
op_pow#
Overloaded ** — return $m raised to the integer power $n.
Comparison#
op_spaceship#
Overloaded <=> — signed comparison returning -1, 0, or 1.
op_eq#
Overloaded == — return 1 when $m equals $n, else 0.
Bitwise#
mul_2exp_gmp#
Return $x shifted left by $e bits ($x * 2**$e).
Synopsis
Math::GMP->new(0b1011)->mul_2exp_gmp(4); # 0b10110000
Equivalent to $x << $e on a Math::GMP value; the operator form
goes through blshift. $e is a plain non-negative integer.
div_2exp_gmp#
Return $x shifted right by $e bits (int($x / 2**$e)).
Synopsis
Math::GMP->new(200)->div_2exp_gmp(2); # 50
Truncates toward zero, matching libgmp’s mpz_tdiv_q_2exp.
Use brshift for the overloaded-operator spelling.
mod_2exp_gmp#
Return the low $cnt bits of $x ($x mod 2**$cnt).
Synopsis
Math::GMP->new(0b10001011)->mod_2exp_gmp(4); # 0b1011
Does not modify $x. The sign of the result matches $x — this
is truncated (tdiv) rather than Euclidean (mmod) semantics.
band#
Bit-wise AND of $m and $n.
Synopsis
Math::GMP->new(6)->band(3); # 0b110 & 0b011 = 0b010 = 2
Overload hook for &. The optional third argument (swap) is
accepted and ignored.
bxor#
Bit-wise XOR of $m and $n.
bior#
Bit-wise inclusive OR of $m and $n.
blshift#
Return $m << $n — left shift by $n bits.
brshift#
Return $m >> $n — right shift by $n bits, truncating toward zero.
Synopsis
Math::GMP->new(0b11001)->brshift(3); # 0b11 = 3
Overload hook for >>. Uses truncated division, so negative
values shift toward zero rather than toward minus infinity.
gmp_tstbit#
Return bit $n of $x (0-indexed, from the least significant end).
Number theory#
powm_gmp#
Compute $base ** $exp mod $mod without building the full power.
mmod_gmp#
Return the non-negative remainder of $a / $b.
bmodinv#
Return the modular inverse of $x mod $y.
legendre#
Return the Legendre symbol ($m / $n) as -1, 0, or 1.
jacobi#
Return the Jacobi symbol ($m / $n) as -1, 0, or 1.
probab_prime#
Probabilistic primality test: return 0, 1, or 2.
bgcd#
Return the greatest common divisor of $m and $n.
blcm#
Return the least common multiple of $m and $n.
fibonacci#
Return the $n-th Fibonacci number.
bfac#
Return $n! — the factorial of a non-negative integer.
bnok#
Return the binomial coefficient $n choose $k.
Roots and powers#
broot#
Return the integer $n-th root of $x, truncated toward zero.
brootrem#
Return the integer $n-th root of $x and the shortfall.
bsqrt#
Return the integer square root of $x.
bsqrtrem#
Return the integer square root of $x and the shortfall.
Synopsis
my ($r, $q) = Math::GMP->new(7)->bsqrtrem; # 2, 3
**because 2**2 + 3 == 7**
The returned list satisfies $r ** 2 + $q == $x.
is_perfect_power#
Return 1 when $x is a perfect power $a ** $b with $b > 1.
is_perfect_square#
Return 1 when $x is the square of an integer, else 0.
Synopsis
Math::GMP->new(49)->is_perfect_square; # 1
Math::GMP->new(50)->is_perfect_square; # 0
Overload glue#
nomethod#
Fallback stub for overloaded operations that have no handler.
op_stringify#
Overloaded "" — stringify a Math::GMP as its decimal digits.
op_numify#
Overloaded 0+ — convert a Math::GMP to a plain Perl number.
op_bool#
Overloaded bool — true when $x is non-zero.
Library info#
gmp_lib_version#
Return the version of libgmp currently loaded into the process.
Other Functions#
new#
Build a Math::GMP object from a string or integer scalar.