Go to the first, previous, next, last section, table of contents.

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 put 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.

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.

Go to the first, previous, next, last section, table of contents.