### 5.6 Division Functions

Division is undefined if the divisor is zero. Passing a zero divisor to the division or modulo functions (including the modular powering functions `mpz_powm` and `mpz_powm_ui`), will cause an intentional division by zero. This lets a program handle arithmetic exceptions in these functions the same way as for normal C `int` arithmetic.

Function: void mpz_cdiv_q (mpz_t q, const mpz_t n, const mpz_t d)
Function: void mpz_cdiv_r (mpz_t r, const mpz_t n, const mpz_t d)
Function: void mpz_cdiv_qr (mpz_t q, mpz_t r, const mpz_t n, const mpz_t d)
Function: unsigned long int mpz_cdiv_q_ui (mpz_t q, const mpz_t n, unsigned long int d)
Function: unsigned long int mpz_cdiv_r_ui (mpz_t r, const mpz_t n, unsigned long int d)
Function: unsigned long int mpz_cdiv_qr_ui (mpz_t q, mpz_t r, const mpz_t n, unsigned long int d)
Function: unsigned long int mpz_cdiv_ui (const mpz_t n, unsigned long int d)
Function: void mpz_cdiv_q_2exp (mpz_t q, const mpz_t n, mp_bitcnt_t b)
Function: void mpz_cdiv_r_2exp (mpz_t r, const mpz_t n, mp_bitcnt_t b)

Function: void mpz_fdiv_q (mpz_t q, const mpz_t n, const mpz_t d)
Function: void mpz_fdiv_r (mpz_t r, const mpz_t n, const mpz_t d)
Function: void mpz_fdiv_qr (mpz_t q, mpz_t r, const mpz_t n, const mpz_t d)
Function: unsigned long int mpz_fdiv_q_ui (mpz_t q, const mpz_t n, unsigned long int d)
Function: unsigned long int mpz_fdiv_r_ui (mpz_t r, const mpz_t n, unsigned long int d)
Function: unsigned long int mpz_fdiv_qr_ui (mpz_t q, mpz_t r, const mpz_t n, unsigned long int d)
Function: unsigned long int mpz_fdiv_ui (const mpz_t n, unsigned long int d)
Function: void mpz_fdiv_q_2exp (mpz_t q, const mpz_t n, mp_bitcnt_t b)
Function: void mpz_fdiv_r_2exp (mpz_t r, const mpz_t n, mp_bitcnt_t b)

Function: void mpz_tdiv_q (mpz_t q, const mpz_t n, const mpz_t d)
Function: void mpz_tdiv_r (mpz_t r, const mpz_t n, const mpz_t d)
Function: void mpz_tdiv_qr (mpz_t q, mpz_t r, const mpz_t n, const mpz_t d)
Function: unsigned long int mpz_tdiv_q_ui (mpz_t q, const mpz_t n, unsigned long int d)
Function: unsigned long int mpz_tdiv_r_ui (mpz_t r, const mpz_t n, unsigned long int d)
Function: unsigned long int mpz_tdiv_qr_ui (mpz_t q, mpz_t r, const mpz_t n, unsigned long int d)
Function: unsigned long int mpz_tdiv_ui (const mpz_t n, unsigned long int d)
Function: void mpz_tdiv_q_2exp (mpz_t q, const mpz_t n, mp_bitcnt_t b)
Function: void mpz_tdiv_r_2exp (mpz_t r, const mpz_t n, mp_bitcnt_t b)

  Divide n by d, forming a quotient q and/or remainder r. For the `2exp` functions, d=2^b. The rounding is in three styles, each suiting different applications.

  - `cdiv` rounds q up towards +infinity, and r will have the opposite sign to d. The `c` stands for “ceil”.
  - `fdiv` rounds q down towards -infinity, and r will have the same sign as d. The `f` stands for “floor”.
  - `tdiv` rounds q towards zero, and r will have the same sign as n. The `t` stands for “truncate”.

  In all cases q and r will satisfy n=q*d+r, and r will satisfy 0<=abs(r)<abs(d).

  The `q` functions calculate only the quotient, the `r` functions only the remainder, and the `qr` functions calculate both. Note that for `qr` the same variable cannot be passed for both q and r, or results will be unpredictable.

  For the `ui` variants the return value is the remainder, and in fact returning the remainder is all the `div_ui` functions do. For `tdiv` and `cdiv` the remainder can be negative, so for those the return value is the absolute value of the remainder.

  For the `2exp` variants the divisor is 2^b. These functions are implemented as right shifts and bit masks, but of course they round the same as the other functions.

  For positive n both `mpz_fdiv_q_2exp` and `mpz_tdiv_q_2exp` are simple bitwise right shifts. For negative n, `mpz_fdiv_q_2exp` is effectively an arithmetic right shift treating n as twos complement the same as the bitwise logical functions do, whereas `mpz_tdiv_q_2exp` effectively treats n as sign and magnitude.

Function: void mpz_mod (mpz_t r, const mpz_t n, const mpz_t d)
Function: unsigned long int mpz_mod_ui (mpz_t r, const mpz_t n, unsigned long int d)

  Set r to n `mod` d. The sign of the divisor is ignored; the result is always non-negative.

  `mpz_mod_ui` is identical to `mpz_fdiv_r_ui` above, returning the remainder as well as setting r. See `mpz_fdiv_ui` above if only the return value is wanted.

Function: void mpz_divexact (mpz_t q, const mpz_t n, const mpz_t d)
Function: void mpz_divexact_ui (mpz_t q, const mpz_t n, unsigned long d)

  Set q to n/d. These functions produce correct results only when it is known in advance that d divides n.

  These routines are much faster than the other division functions, and are the best choice when exact division is known to occur, for example reducing a rational to lowest terms.

Function: int mpz_divisible_p (const mpz_t n, const mpz_t d)
Function: int mpz_divisible_ui_p (const mpz_t n, unsigned long int d)
Function: int mpz_divisible_2exp_p (const mpz_t n, mp_bitcnt_t b)

  Return non-zero if n is exactly divisible by d, or in the case of `mpz_divisible_2exp_p` by 2^b.

  n is divisible by d if there exists an integer q satisfying n = q*d. Unlike the other division functions, d=0 is accepted and following the rule it can be seen that only 0 is considered divisible by 0.

Function: int mpz_congruent_p (const mpz_t n, const mpz_t c, const mpz_t d)
Function: int mpz_congruent_ui_p (const mpz_t n, unsigned long int c, unsigned long int d)
Function: int mpz_congruent_2exp_p (const mpz_t n, const mpz_t c, mp_bitcnt_t b)

  Return non-zero if n is congruent to c modulo d, or in the case of `mpz_congruent_2exp_p` modulo 2^b.

  n is congruent to c mod d if there exists an integer q satisfying n = c + q*d. Unlike the other division functions, d=0 is accepted and following the rule it can be seen that n and c are considered congruent mod 0 only when exactly equal.