Arithmetic Functions
====================

 - Function: void mpz_add (mpz_t ROP, mpz_t OP1, mpz_t OP2)
 - Function: void mpz_add_ui (mpz_t ROP, mpz_t OP1, unsigned long int
          OP2)
     Set ROP to OP1 + OP2.

 - Function: void mpz_sub (mpz_t ROP, mpz_t OP1, mpz_t OP2)
 - Function: void mpz_sub_ui (mpz_t ROP, mpz_t OP1, unsigned long int
          OP2)
     Set ROP to OP1 - OP2.

 - Function: void mpz_mul (mpz_t ROP, mpz_t OP1, mpz_t OP2)
 - Function: void mpz_mul_ui (mpz_t ROP, mpz_t OP1, unsigned long int
          OP2)
     Set ROP to OP1 times OP2.

 - Function: void mpz_mul_2exp (mpz_t ROP, mpz_t OP1, unsigned long int
          OP2)
     Set ROP to OP1 times 2 raised to OP2.  This operation can also be
     defined as a left shift, OP2 steps.

 - Function: void mpz_neg (mpz_t ROP, mpz_t OP)
     Set ROP to -OP.

 - Function: void mpz_abs (mpz_t ROP, mpz_t OP)
     Set ROP to the absolute value of OP.

 - Function: void mpz_fac_ui (mpz_t ROP, unsigned long int OP)
     Set ROP to OP!, the factorial of OP.

Division functions
------------------

   Division is undefined if the divisor is zero, and passing a zero
divisor to the divide or modulo functions, as well passing a zero mod
argument to the `mpz_powm' and `mpz_powm_ui' functions, will make these
functions intentionally divide by zero.  This gives the user the
possibility to handle arithmetic exceptions in these functions in the
same manner as other arithmetic exceptions.

   There are three main groups of division functions:
   * Functions that truncate the quotient towards 0.  The names of these
     functions start with `mpz_tdiv'.  The `t' in the name is short for
     `truncate'.

   * Functions that round the quotient towards -infinity.  The names of
     these routines start with `mpz_fdiv'.  The `f' in the name is
     short for `floor'.

   * Functions that round the quotient towards +infinity.  The names of
     these routines start with `mpz_cdiv'.  The `c' in the name is
     short for `ceil'.

   For each rounding mode, there are a couple of variants.  Here `q'
means that the quotient is computed, while `r' means that the remainder
is computed.  Functions that compute both the quotient and remainder
have `qr' in the name.

 - Function: void mpz_tdiv_q (mpz_t ROP, mpz_t OP1, mpz_t OP2)
 - Function: void mpz_tdiv_q_ui (mpz_t ROP, mpz_t OP1, unsigned long
          int OP2)
     Set ROP to [OP1/OP2].  The quotient is truncated towards 0.

 - Function: void mpz_tdiv_r (mpz_t ROP, mpz_t OP1, mpz_t OP2)
 - Function: void mpz_tdiv_r_ui (mpz_t ROP, mpz_t OP1, unsigned long
          int OP2)
     Set ROP to (OP1 - [OP1/OP2] * OP2).  Unless the remainder is zero,
     it has the same sign as the dividend.

 - Function: void mpz_tdiv_qr (mpz_t ROP1, mpz_t ROP2, mpz_t OP1, mpz_t
          OP2)
 - Function: void mpz_tdiv_qr_ui (mpz_t ROP1, mpz_t ROP2, mpz_t OP1,
          unsigned long int OP2)
     Divide OP1 by OP2 and put the quotient in ROP1 and the remainder
     in ROP2.  The quotient is rounded towards 0.  Unless the remainder
     is zero, it has the same sign as the dividend.

     If ROP1 and ROP2 are the same variable, the results are undefined.

 - Function: void mpz_fdiv_q (mpz_t ROP1, mpz_t OP1, mpz_t OP2)
 - Function: void mpz_fdiv_q_ui (mpz_t ROP, mpz_t OP1, unsigned long
          int OP2)
     Set ROP to OP1/OP2.  The quotient is rounded towards -infinity.

 - Function: void mpz_fdiv_r (mpz_t ROP, mpz_t OP1, mpz_t OP2)
 - Function: unsigned long int mpz_fdiv_r_ui (mpz_t ROP, mpz_t OP1,
          unsigned long int OP2)
     Divide OP1 by OP2 and put the remainder in ROP.  Unless the
     remainder is zero, it has the same sign as the divisor.

     For `mpz_fdiv_r_ui' the remainder is small enough to fit in an
     `unsigned long int', and is therefore returned.

 - Function: void mpz_fdiv_qr (mpz_t ROP1, mpz_t ROP2, mpz_t OP1, mpz_t
          OP2)
 - Function: unsigned long int mpz_fdiv_qr_ui (mpz_t ROP1, mpz_t ROP2,
          mpz_t OP1, unsigned long int OP2)
     Divide OP1 by OP2 and put the quotient in ROP1 and the remainder
     in ROP2.  The quotient is rounded towards -infinity.  Unless the
     remainder is zero, it has the same sign as the divisor.

     For `mpz_fdiv_qr_ui' the remainder is small enough to fit in an
     `unsigned long int', and is therefore returned.

     If ROP1 and ROP2 are the same variable, the results are undefined.

 - Function: unsigned long int mpz_fdiv_ui (mpz_t OP1, unsigned long
          int OP2)
     This function is similar to `mpz_fdiv_r_ui', but the remainder is
     only returned; it is not stored anywhere.

 - Function: void mpz_cdiv_q (mpz_t ROP1, mpz_t OP1, mpz_t OP2)
 - Function: void mpz_cdiv_q_ui (mpz_t ROP, mpz_t OP1, unsigned long
          int OP2)
     Set ROP to OP1/OP2.  The quotient is rounded towards +infinity.

 - Function: void mpz_cdiv_r (mpz_t ROP, mpz_t OP1, mpz_t OP2)
 - Function: unsigned long int mpz_cdiv_r_ui (mpz_t ROP, mpz_t OP1,
          unsigned long int OP2)
     Divide OP1 by OP2 and put the remainder in ROP.  Unless the
     remainder is zero, it has the opposite sign as the divisor.

     For `mpz_cdiv_r_ui' the negated remainder is small enough to fit
     in an `unsigned long int', and it is therefore returned.

 - Function: void mpz_cdiv_qr (mpz_t ROP1, mpz_t ROP2, mpz_t OP1, mpz_t
          OP2)
 - Function: unsigned long int mpz_cdiv_qr_ui (mpz_t ROP1, mpz_t ROP2,
          mpz_t OP1, unsigned long int OP2)
     Divide OP1 by OP2 and put the quotient in ROP1 and the remainder
     in ROP2.  The quotient is rounded towards +infinity.  Unless the
     remainder is zero, it has the opposite sign as the divisor.

     For `mpz_cdiv_qr_ui' the negated remainder is small enough to fit
     in an `unsigned long int', and it is therefore returned.

     If ROP1 and ROP2 are the same variable, the results are undefined.

 - Function: unsigned long int mpz_cdiv_ui (mpz_t OP1, unsigned long
          int OP2)
     Return the negated remainder, similar to `mpz_cdiv_r_ui'.  (The
     difference is that this function doesn't store the remainder
     anywhere.)

 - Function: void mpz_mod (mpz_t ROP, mpz_t OP1, mpz_t OP2)
 - Function: unsigned long int mpz_mod_ui (mpz_t ROP, mpz_t OP1,
          unsigned long int OP2)
     Set ROP to OP1 `mod' OP2.  The sign of the divisor is ignored, and
     the result is always non-negative.

     For `mpz_mod_ui' the remainder is small enough to fit in an
     `unsigned long int', and is therefore returned.

 - Function: void mpz_divexact (mpz_t ROP, mpz_t OP1, mpz_t OP2)
     Set ROP to OP1/OP2.  This function produces correct results only
     when it is known in advance that OP2 divides OP1.

     Since mpz_divexact is much faster than any of the other routines
     that produce the quotient (see References. Jebelean), it is
     the best choice for instances in which exact division is known to
     occur, such as reducing a rational to lowest terms.

 - Function: void mpz_tdiv_q_2exp (mpz_t ROP, mpz_t OP1, unsigned long
          int OP2)
     Set ROP to OP1 divided by 2 raised to OP2.  The quotient is
     rounded towards 0.

 - Function: void mpz_tdiv_r_2exp (mpz_t ROP, mpz_t OP1, unsigned long
          int OP2)
     Divide OP1 by (2 raised to OP2) and put the remainder in ROP.
     Unless it is zero, ROP will have the same sign as OP1.

 - Function: void mpz_fdiv_q_2exp (mpz_t ROP, mpz_t OP1, unsigned long
          int OP2)
     Set ROP to OP1 divided by 2 raised to OP2.  The quotient is
     rounded towards -infinity.

 - Function: void mpz_fdiv_r_2exp (mpz_t ROP, mpz_t OP1, unsigned long
          int OP2)
     Divide OP1 by (2 raised to OP2) and put the remainder in ROP.  The
     sign of ROP will always be positive.

     This operation can also be defined as masking of the OP2 least
     significant bits.

Exponentialization Functions
----------------------------

 - Function: void mpz_powm (mpz_t ROP, mpz_t BASE, mpz_t EXP, mpz_t MOD)
 - Function: void mpz_powm_ui (mpz_t ROP, mpz_t BASE, unsigned long int
          EXP, mpz_t MOD)
     Set ROP to (BASE raised to EXP) `mod' MOD.  If EXP is negative,
     the result is undefined.

 - Function: void mpz_pow_ui (mpz_t ROP, mpz_t BASE, unsigned long int
          EXP)
 - Function: void mpz_ui_pow_ui (mpz_t ROP, unsigned long int BASE,
          unsigned long int EXP)
     Set ROP to BASE raised to EXP.  The case of 0^0 yields 1.

Square Root Functions
---------------------

 - Function: void mpz_sqrt (mpz_t ROP, mpz_t OP)
     Set ROP to the truncated integer part of the square root of OP.

 - Function: void mpz_sqrtrem (mpz_t ROP1, mpz_t ROP2, mpz_t OP)
     Set ROP1 to the truncated integer part of the square root of OP,
     like `mpz_sqrt'.  Set ROP2 to OP-ROP1*ROP1, (i.e., zero if OP is a
     perfect square).

     If ROP1 and ROP2 are the same variable, the results are undefined.

 - Function: int mpz_perfect_square_p (mpz_t OP)
     Return non-zero if OP is a perfect square, i.e., if the square
     root of OP is an integer.  Return zero otherwise.

Number Theoretic Functions
--------------------------

 - Function: int mpz_probab_prime_p (mpz_t OP, int REPS)
     If this function returns 0, OP is definitely not prime.  If it
     returns 1, then OP is `probably' prime.  The probability of a
     false positive is (1/4)**REPS.  A reasonable value of reps is 25.

     An implementation of the probabilistic primality test found in
     Seminumerical Algorithms (see References. Knuth).

 - Function: void mpz_gcd (mpz_t ROP, mpz_t OP1, mpz_t OP2)
     Set ROP to the greatest common divisor of OP1 and OP2.

 - Function: unsigned long int mpz_gcd_ui (mpz_t ROP, mpz_t OP1,
          unsigned long int OP2)
     Compute the greatest common divisor of OP1 and OP2.  If ROP is not
     NULL, store the result there.

     If the result is small enough to fit in an `unsigned long int', it
     is returned.  If the result does not fit, 0 is returned, and the
     result is equal to the argument OP1.  Note that the result will
     always fit if OP2 is non-zero.

 - Function: void mpz_gcdext (mpz_t G, mpz_t S, mpz_t T, mpz_t A, mpz_t
          B)
     Compute G, S, and T, such that AS + BT = G = `gcd' (A, B).  If T is
     NULL, that argument is not computed.

 - Function: int mpz_invert (mpz_t ROP, mpz_t OP1, mpz_t OP2)
     Compute the inverse of OP1 modulo OP2 and put the result in ROP.
     Return non-zero if an inverse exist, zero otherwise.  When the
     function returns zero, do not assume anything about the value in
     ROP.

 - Function: int mpz_jacobi (mpz_t OP1, mpz_t OP2)
 - Function: int mpz_legendre (mpz_t OP1, mpz_t OP2)
     Compute the Jacobi and Legendre symbols, respectively.