MP Basics
*********

   All declarations needed to use MP are collected in the include file
`gmp.h'.  It is designed to work with both C and C++ compilers.

Nomenclature and Types
======================

In this manual, "integer" usually means a multiple precision integer, as
defined by the MP library.  The C data type for such integers is
`mpz_t'.  Here are some examples of how to declare such integers:

     mpz_t sum;
     
     struct foo { mpz_t x, y; };
     
     mpz_t vec[20];

"Rational number" means a multiple precision fraction.  The C data type
for these fractions is `mpq_t'.  For example:

     mpq_t quotient;

"Floating point number" or "Float" for short, is an arbitrary precision
mantissa with an limited precision exponent.  The C data type for such
objects is `mpf_t'.

A "limb" means the part of a multi-precision number that fits in a
single word.  (We chose this word because a limb of the human body is
analogous to a digit, only larger, and containing several digits.)
Normally a limb contains 32 or 64 bits.  The C data type for a limb is
`mp_limb_t'.

Function Classes
================

   There are six classes of functions in the MP library:

  1. Functions for signed integer arithmetic, with names beginning with
     `mpz_'.  The associated type is `mpz_t'.  There are about 100
     functions in this class.

  2. Functions for rational number arithmetic, with names beginning with
     `mpq_'.  The associated type is `mpq_t'.  There are about 20
     functions in this class, but the functions in the previous class
     can be used for performing arithmetic on the numerator and
     denominator separately.

  3. Functions for floating-point arithmetic, with names beginning with
     `mpf_'.  The associated type is `mpf_t'.  There are about 50
     functions is this class.

  4. Functions compatible with Berkeley MP, such as `itom', `madd', and
     `mult'.  The associated type is `MINT'.

  5. Fast low-level functions that operate on natural numbers.  These
     are used by the functions in the preceding groups, and you can
     also call them directly from very time-critical user programs.
     These functions' names begin with `mpn_'.  There are about 30
     (hard-to-use) functions in this class.

     The associated type is array of `mp_limb_t'.

  6. Miscellaneous functions.  Functions for setting up custom
     allocation.

MP Variable Conventions
=======================

   As a general rule, all MP functions expect output arguments before
input arguments.  This notation is based on an analogy with the
assignment operator.  (The BSD MP compatibility functions disobey this
rule, having the output argument(s) last.)

   MP allows you to use the same variable for both input and output in
the same expression.  For example, the main function for integer
multiplication, `mpz_mul', can be used like this: `mpz_mul (x, x, x)'.
This computes the square of X and puts the result back in X.

   Before you can assign to an MP variable, you need to initialize it
by calling one of the special initialization functions.  When you're
done with a variable, you need to clear it out, using one of the
functions for that purpose.  Which function to use depends on the type
of variable.  See the chapters on integer functions, rational number
functions, and floating-point functions for details.

   A variable should only be initialized once, or at least cleared out
between each initialization.  After a variable has been initialized, it
may be assigned to any number of times.

   For efficiency reasons, avoid to initialize and clear out a variable
in loops.  Instead, initialize it before entering the loop, and clear
it out after the loop has exited.

   You don't need to be concerned about allocating additional space for
MP variables.  All functions in MP automatically allocate additional
space when a variable does not already have enough space.  They do not,
however, reduce the space when a smaller number is stored in the
object.  Most of the time, this policy is best, since it avoids
frequent re-allocation.

Useful Macros and Constants
===========================

 - Global Constant: const int mp_bits_per_limb
     The number of bits per limb.

 - Macro: __GNU_MP_VERSION
 - Macro: __GNU_MP_VERSION_MINOR
     The major and minor MP version, respectively, as integers.

Compatibility with Version 1.x
==============================

   This version of MP is upward compatible with previous versions of
MP, with a few exceptions.

  1. Integer division functions round the result differently.  The old
     functions (`mpz_div', `mpz_divmod', `mpz_mdiv', `mpz_mdivmod',
     etc) now all use floor rounding (i.e., they round the quotient to
     -infinity).  There are a lot of new functions for integer
     division, giving the user better control over the rounding.

  2. The function `mpz_mod' now compute the true *mod* function.

  3. The functions `mpz_powm' and `mpz_powm_ui' now use *mod* for
     reduction.

  4. The assignment functions for rational numbers do no longer
     canonicalize their results.  In the case a non-canonical result
     could arise from an assignment, the user need to insert an
     explicit call to `mpq_canonicalize'.  This change was made for
     efficiency.

  5. Output generated by `mpz_out_raw' in this release cannot be read
     by `mpz_inp_raw' in previous releases.  This change was made for
     making the file format truly portable between machines with
     different word sizes.

  6. Several `mpn' functions have changed.  But they were intentionally
     undocumented in previous releases.

  7. The functions `mpz_cmp_ui', `mpz_cmp_si', and `mpq_cmp_ui' are now
     implementated as macros, and thereby sometimes evaluate their
     arguments multiple times.

  8. The functions `mpz_pow_ui' and `mpz_ui_pow_ui' now yield 1 for
     0^0.  (In version 1, they yielded 0.)


Getting the Latest Version of MP
================================

   The latest version of the MP library is available by anonymous ftp
from from `prep.ai.mit.edu'.  The file name is
`/pub/gnu/gmp-M.N.tar.gz'.  Many sites around the world mirror `prep';
please use a mirror site near you.