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.