# Math::GMP

📦 max

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: ```none 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: ```none 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`](GMP/gmp_copy.md) Return an independent copy of `$x`. ### Conversion #### `stringify` Return the decimal string representation of a `Math::GMP` value. #### [`get_str_gmp`](GMP/get_str_gmp.md) Return the string representation of `$x` in the given base. #### [`sizeinbase_gmp`](GMP/sizeinbase_gmp.md) 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`](GMP/intify.md) Return `$x` as a plain signed Perl integer. ### Arithmetic #### [`add_ui_gmp`](GMP/add_ui_gmp.md) 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`](GMP/bmulf.md) Return `$x` multiplied by a floating-point value, truncated to an integer. #### `op_div` Overloaded `/` — integer division `int($m / $n)`, truncated toward zero. #### [`bdiv`](GMP/bdiv.md) 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** ```perl 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** ```perl 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** ```perl 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** ```perl 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`](GMP/blshift.md) Return `$m << $n` — left shift by `$n` bits. #### `brshift` Return `$m >> $n` — right shift by `$n` bits, truncating toward zero. **Synopsis** ```perl 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`](GMP/gmp_tstbit.md) Return bit `$n` of `$x` (0-indexed, from the least significant end). ### Number theory #### [`powm_gmp`](GMP/powm_gmp.md) Compute `$base ** $exp mod $mod` without building the full power. #### [`mmod_gmp`](GMP/mmod_gmp.md) Return the non-negative remainder of `$a / $b`. #### [`bmodinv`](GMP/bmodinv.md) Return the modular inverse of `$x` mod `$y`. #### [`legendre`](GMP/legendre.md) 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`](GMP/probab_prime.md) Probabilistic primality test: return `0`, `1`, or `2`. #### [`bgcd`](GMP/bgcd.md) Return the greatest common divisor of `$m` and `$n`. #### [`blcm`](GMP/blcm.md) Return the least common multiple of `$m` and `$n`. #### [`fibonacci`](GMP/fibonacci.md) Return the `$n`-th Fibonacci number. #### [`bfac`](GMP/bfac.md) Return `$n!` — the factorial of a non-negative integer. #### [`bnok`](GMP/bnok.md) Return the binomial coefficient `$n choose $k`. ### Roots and powers #### [`broot`](GMP/broot.md) Return the integer `$n`-th root of `$x`, truncated toward zero. #### [`brootrem`](GMP/brootrem.md) Return the integer `$n`-th root of `$x` and the shortfall. #### [`bsqrt`](GMP/bsqrt.md) Return the integer square root of `$x`. #### `bsqrtrem` Return the integer square root of `$x` and the shortfall. **Synopsis** ```perl 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`](GMP/is_perfect_power.md) 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** ```perl 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`](GMP/op_numify.md) 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`](GMP/gmp_lib_version.md) Return the version of `libgmp` currently loaded into the process. ### Other Functions #### [`new`](GMP/new.md) Build a `Math::GMP` object from a string or integer scalar.