# Integers

## mpz type

class gmpy2.mpz(n=0, /)
class gmpy2.mpz(s, /, base=0)

  Return an immutable integer constructed from a numeric value n (truncating n to its integer part) or a string s made of digits in the given base. Every input, that is accepted by the `int` type constructor is also accepted.

  The base may vary from 2 to 62, or if base is 0, then binary, octal, or hexadecimal strings are recognized by leading '0b', '0o', or '0x' characters (case is ignored), otherwise the string is assumed to be decimal. For bases up to 36, digits case is ignored. For bases 37 to 62, upper-case letter represent the usual 10..35 range, while lower-case letter represent 36..61. Optionally the string can be preceded by '+' or '-'. White space and underscore is simply ignored.

  __format__(fmt) → str

    Return a Python string by formatting `mpz` 'x' using the format string 'fmt'. A valid format string consists of:

    > optional alignment code:

    > > '<' -> left shifted in field '>' -> right shifted in field '^' -> centered in field

    > optional leading sign code:

    > > '+' -> always display leading sign '-' -> only display minus sign ' ' -> minus for negative values, space for positive values

    > optional base indicator

    > > '#' -> precede binary, octal, or hex with 0b, 0o or 0x

    > optional width

    > optional conversion code:

    > > 'd' -> decimal format 'b' -> binary format 'o' -> octal format 'x' -> hex format 'X' -> upper-case hex format

    The default format is 'd'.

  as_integer_ratio() → tuple[mpz, mpz]

    Return a pair of integers, whose ratio is exactly equal to the original number. The ratio is in lowest terms and has a positive denominator.

  bit_clear(n, /) → mpz

    Return a copy of x with the n-th bit cleared.

  bit_count() → int

    Return the number of 1-bits set in abs(x).

  bit_flip(n, /) → mpz

    Return a copy of x with the n-th bit inverted.

  bit_length() → int

    Return the number of significant bits in the radix-2 representation of x. Note: mpz(0).bit_length() returns 0.

  bit_scan0(n=0, /) → int | None

    Return the index of the first 0-bit of x with index >= n. n >= 0. If there are no more 0-bits in x at or above index n (which can only happen for x<0, assuming an infinitely long 2's complement format), then `None` is returned.

  bit_scan1(n=0, /) → int | None

    Return the index of the first 1-bit of x with index >= n. n >= 0. If there are no more 1-bits in x at or above index n (which can only happen for x>=0, assuming an infinitely long 2's complement format), then `None` is returned.

  bit_set(n, /) → mpz

    Return a copy of x with the n-th bit set.

  bit_test(n, /) → bool

    Return the value of the n-th bit of x.

  conjugate() → mpz

    Return the conjugate of x (which is just a new reference to x since x is not a complex number).

  digits(base=10, /) → str

    Return Python string representing x in the given base. Values for base can range between 2 to 62. A leading '-' is present if x<0 but no leading '+' is present if x>=0.

  classmethod from_bytes(bytes, byteorder='big', *, signed=False) → mpz

    Return the integer represented by the given array of bytes.

    > bytes

    >   Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. `bytes` and `bytearray` are examples of built-in objects that support the buffer protocol.

    > byteorder

    >   The byte order used to represent the integer. If byteorder is 'big', the most significant byte is at the beginning of the byte array. If byteorder is 'little', the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder` as the byte order value.

    > signed

    >   Indicates whether two's complement is used to represent the integer.

  is_congruent(y, m, /) → bool

    Returns `True` if x is congruent to y modulo m, else return `False`.

  is_divisible(d, /) → bool

    Returns `True` if x is divisible by d, else return `False`.

  is_even() → bool

    Return `True` if x is even, `False` otherwise.

  is_odd() → bool

    Return `True` if x is odd, `False` otherwise.

  is_power() → bool

    Return `True` if x is a perfect power (there exists a y and an n > 1, such that x=y**n), else return `False`.

  is_prime(n=25, /) → bool

    Return `True` if x is probably prime, else `False` if x is definitely composite. x is checked for small divisors and up to n Miller-Rabin tests are performed.

  is_probab_prime(n=25, /) → int

    Return 2 if x is definitely prime, 1 if x is probably prime, or return 0 if x is definitely non-prime. x is checked for small divisors and up to n Miller-Rabin tests are performed. Reasonable values of n are between 15 and 50.

  is_square() → bool

    Returns `True` if x is a perfect square, else return `False`.

  num_digits(base=10, /) → int

    Return length of string representing the absolute value of x in the given base. Values for base can range between 2 and 62. The value returned may be 1 too large.

  to_bytes(length=1, byteorder='big', *, signed=False) → bytes

    Return an array of bytes representing an integer.

    > length

    >   Length of bytes object to use. An `OverflowError` is raised if the integer is not representable with the given number of bytes.

    > byteorder

    >   The byte order used to represent the integer. If byteorder is 'big', the most significant byte is at the beginning of the byte array. If byteorder is 'little', the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder` as the byte order value.

    > signed

    >   Determines whether two's complement is used to represent the integer. If signed is `False` and a negative integer is given, an `OverflowError` is raised.

  denominator

    the denominator of a rational number in lowest terms

  imag

    the imaginary part of a complex number

  numerator

    the numerator of a rational number in lowest terms

  real

    the real part of a complex number

## mpz Functions

gmpy2.bincoef(n, k, /) → mpz

  Return the binomial coefficient ('n choose k'). k >= 0.

gmpy2.bit_clear(x, n, /) → mpz

  Return a copy of x with the n-th bit cleared.

gmpy2.bit_count(x, /) → int

  Return the number of 1-bits set in abs(x).

gmpy2.bit_flip(x, n, /) → mpz

  Return a copy of x with the n-th bit inverted.

gmpy2.bit_length(x, /) → int

  Return the number of significant bits in the radix-2 representation of x. Note: bit_length(0) returns 0.

gmpy2.bit_mask(n, /) → mpz

  Return an `mpz` exactly n bits in length with all bits set.

gmpy2.bit_scan0(x, n=0, /) → int | None

  Return the index of the first 0-bit of x with index >= n. n >= 0. If there are no more 0-bits in x at or above index n (which can only happen for x<0, assuming an infinitely long 2's complement format), then `None` is returned.

gmpy2.bit_scan1(x, n=0, /) → int | None

  Return the index of the first 1-bit of x with index >= n. n >= 0. If there are no more 1-bits in x at or above index n (which can only happen for x>=0, assuming an infinitely long 2's complement format), then `None` is returned.

gmpy2.bit_set(x, n, /) → mpz

  Return a copy of x with the n-th bit set.

gmpy2.bit_test(x, n, /) → bool

  Return the value of the n-th bit of x.

gmpy2.c_div(x, y, /) → mpz

  Return the quotient of x divided by y. The quotient is rounded towards +Inf (ceiling rounding). x and y must be integers.

gmpy2.c_div_2exp(x, n, /) → mpz

  Returns the quotient of x divided by 2**n. The quotient is rounded towards +Inf (ceiling rounding). x must be an integer. n must be >0.

gmpy2.c_divmod(x, y, /) → tuple[mpz, mpz]

  Return the quotient and remainder of x divided by y. The quotient is rounded towards +Inf (ceiling rounding) and the remainder will have the opposite sign of y. x and y must be integers.

gmpy2.c_divmod_2exp(x, n, /) → tuple[mpz, mpz]

  Return the quotient and remainder of x divided by 2**n. The quotient is rounded towards +Inf (ceiling rounding) and the remainder will be negative. x must be an integer. n must be >0.

gmpy2.c_mod(x, y, /) → mpz

  Return the remainder of x divided by y. The remainder will have the opposite sign of y. x and y must be integers.

gmpy2.c_mod_2exp(x, n, /) → mpz

  Return the remainder of x divided by 2**n. The remainder will be negative. x must be an integer. n must be >0.

gmpy2.comb(n, k, /) → mpz

  Return the number of combinations of 'n things, taking k at a time'. k >= 0. Same as bincoef(n, k)

gmpy2.divexact(x, y, /) → mpz

  Return the quotient of x divided by y. Faster than standard division but requires the remainder is zero!

gmpy2.divm(a, b, m, /) → mpz

  Return x such that b*x == a mod m. Raises a `ZeroDivisionError` exception if no such value x exists.

gmpy2.double_fac(n, /) → mpz

  Return the exact double factorial (n!!) of n. The double factorial is defined as n*(n-2)*(n-4)...

gmpy2.f_div(x, y, /) → mpz

  Return the quotient of x divided by y. The quotient is rounded towards -Inf (floor rounding). x and y must be integers.

gmpy2.f_div_2exp(x, n, /) → mpz

  Return the quotient of x divided by 2**n. The quotient is rounded towards -Inf (floor rounding). x must be an integer. n must be >0.

gmpy2.f_divmod(x, y, /) → tuple[mpz, mpz]

  Return the quotient and remainder of x divided by y. The quotient is rounded towards -Inf (floor rounding) and the remainder will have the same sign as y. x and y must be integers.

gmpy2.f_divmod_2exp(x, n, /) → tuple[mpz, mpz]

  Return quotient and remainder after dividing x by 2**n. The quotient is rounded towards -Inf (floor rounding) and the remainder will be positive. x must be an integer. n must be >0.

gmpy2.f_mod(x, y, /) → mpz

  Return the remainder of x divided by y. The remainder will have the same sign as y. x and y must be integers.

gmpy2.f_mod_2exp(x, n, /) → mpz

  Return remainder of x divided by 2**n. The remainder will be positive. x must be an integer. n must be >0.

gmpy2.fac(n, /) → mpz

  Return the exact factorial of n.

  See factorial(n) to get the floating-point approximation.

gmpy2.fib(n, /) → mpz

  Return the n-th Fibonacci number.

gmpy2.fib2(n, /) → tuple[mpz, mpz]

  Return a 2-tuple with the (n-1)-th and n-th Fibonacci numbers.

gmpy2.gcd(*integers, /) → mpz

  Return the greatest common divisor of integers.

gmpy2.gcdext(a, b, /) → tuple[mpz, mpz, mpz]

  Return a 3-element tuple (g,s,t) such that g == gcd(a,b) and g == a*s + b*t.

gmpy2.hamdist(x, y, /) → int

  Return the Hamming distance (number of bit-positions where the bits differ) between integers x and y.

gmpy2.invert(x, m, /) → mpz

  Return y such that x*y == 1 modulo m. Raises `ZeroDivisionError` if no inverse exists.

gmpy2.iroot(x, n, /) → tuple[mpz, bool]

  Return the integer n-th root of x and boolean value that is `True` iff the root is exact. x >= 0. n > 0.

gmpy2.iroot_rem(x, n, /) → tuple[mpz, mpz]

  Return a 2-element tuple (y,r), such that y is the integer n-th root of x and x=y**n + r. x >= 0. n > 0.

gmpy2.is_congruent(x, y, m, /) → bool

  Returns `True` if x is congruent to y modulo m, else return `False`.

gmpy2.is_divisible(x, d, /) → bool

  Returns `True` if x is divisible by d, else return `False`.

gmpy2.is_even(x, /) → bool

  Return `True` if x is even, `False` otherwise.

gmpy2.is_odd(x, /) → bool

  Return `True` if x is odd, `False` otherwise.

gmpy2.is_power(x, /) → bool

  Return `True` if x is a perfect power (there exists a y and an n > 1, such that x=y**n), else return `False`.

gmpy2.is_prime(x, n=25, /) → bool

  Return `True` if x is probably prime, else `False` if x is definitely composite. x is checked for small divisors and up to n Miller-Rabin tests are performed.

gmpy2.is_probab_prime(x, n=25, /) → int

  Return 2 if x is definitely prime, 1 if x is probably prime, or return 0 if x is definitely non-prime. x is checked for small divisors and up to n Miller-Rabin tests are performed. Reasonable values of n are between 15 and 50.

gmpy2.is_square(x, /) → bool

  Returns `True` if x is a perfect square, else return `False`.

gmpy2.isqrt(x, /) → mpz

  Return the integer square root of a non-negative integer x.

gmpy2.isqrt_rem(x, /)

  Return a 2-element tuple (s,t) such that s=isqrt(x) and t=x-s*s. x >=0.

gmpy2.jacobi(x, y, /) → mpz

  Return the Jacobi symbol (x|y). y must be odd and >0.

gmpy2.kronecker(x, y, /) → mpz

  Return the Kronecker-Jacobi symbol (x|y).

gmpy2.lcm(*integers, /) → mpz

  Return the lowest common multiple of integers.

gmpy2.legendre(x, y, /) → mpz

  Return the Legendre symbol (x|y). y is assumed to be an odd prime.

gmpy2.lucas(n, /) → mpz

  Return the n-th Lucas number.

gmpy2.lucas2(n, /) → tuple[mpz, mpz]

  Return a 2-tuple with the (n-1)-th and n-th Lucas numbers.

gmpy2.mpz_random(random_state, int, /) → mpz

  Return uniformly distributed random integer between 0 and n-1.

gmpy2.mpz_rrandomb(random_state, bit_count, /) → mpz

  Return a random integer between 0 and 2**bit_count-1 with long sequences of zeros and one in its binary representation.

gmpy2.mpz_urandomb(random_state, bit_count, /) → mpz

  Return uniformly distributed random integer between 0 and 2**bit_count-1.

gmpy2.multi_fac(n, m, /) → mpz

  Return the exact m-multi factorial of n. The m-multifactorial is defined as n*(n-m)*(n-2m)...

gmpy2.next_prime(x, /) → mpz

  Return the next probable prime number > x.

gmpy2.num_digits(x, base=10, /) → int

  Return length of string representing the absolute value of x in the given base. Values for base can range between 2 and 62. The value returned may be 1 too large.

gmpy2.pack(lst, n, /) → mpz

  Pack a list of integers lst into a single `mpz` by concatenating each integer element of lst after padding to length n bits. Raises an error if any integer is negative or greater than n bits in length.

gmpy2.popcount(x, /) → int

  Return the number of 1-bits set in x. If x<0, the number of 1-bits is infinite so -1 is returned in that case.

gmpy2.powmod(x, y, m, /) → mpz

  Return (x**y) mod m. Same as the three argument version of Python's built-in `pow`, but converts all three arguments to `mpz`.

gmpy2.powmod_exp_list(base, exp_lst, mod, /) → list[mpz, ...]

  Returns list(powmod(base, i, mod) for i in exp_lst). Will always release the GIL. (Experimental in gmpy2 2.1.x).

gmpy2.powmod_base_list(base_lst, exp, mod, /) → list[mpz, ...]

  Returns list(powmod(i, exp, mod) for i in base_lst). Will always release the GIL. (Experimental in gmpy2 2.1.x).

gmpy2.powmod_sec(x, y, m, /) → mpz

  Return (x**y) mod m. Calculates x ** y (mod m) but using a constant time algorithm to reduce the risk of side channel attacks. y must be an integer >0. m must be an odd integer.

gmpy2.prev_prime(x, /) → mpz

  Return the previous probable prime number < x. Only present when compiled with GMP 6.3.0 or later.

gmpy2.primorial(n, /) → mpz

  Return the product of all positive prime numbers less than or equal to n.

gmpy2.remove(x, f, /) → tuple[mpz, mpz]

  Return a 2-element tuple (y,m) such that x=y*(f**m) and f does not divide y. Remove the factor f from x as many times as possible. m is the multiplicity f in x. f > 1.

gmpy2.t_div(x, y, /) → mpz

  Return the quotient of x divided by y. The quotient is rounded towards 0. x and y must be integers.

gmpy2.t_div_2exp(x, n, /) → mpz

  Return the quotient of x divided by 2**n. The quotient is rounded towards zero (truncation). n must be >0.

gmpy2.t_divmod(x, y, /) → tuple[mpz, mpz]

  Return the quotient and remainder of x divided by y. The quotient is rounded towards zero (truncation) and the remainder will have the same sign as x. x and y must be integers.

gmpy2.t_divmod_2exp(x, n, /) → tuple[mpz, mpz]

  Return the quotient and remainder of x divided by 2**n. The quotient is rounded towards zero (truncation) and the remainder will have the same sign as x. x must be an integer. n must be >0.

gmpy2.t_mod(x, y, /) → mpz

  Return the remainder of x divided by y. The remainder will have the same sign as x. x and y must be integers.

gmpy2.t_mod_2exp(x, n, /) → mpz

  Return the remainder of x divided by 2**n. The remainder will have the same sign as x. x must be an integer. n must be >0.

gmpy2.unpack(x, n, /) → list

  Unpack an integer x into a list of n-bit values. Equivalent to repeated division by 2**n. Raises error if x is negative.