All declarations needed to use GMP are collected in the include file `gmp.h'. It is designed to work with both C and C++ compilers.
Using functions, macros, data types, etc. not documented in this manual is strongly discouraged. If you do so your application is guaranteed to be incompatible with future versions of GMP.
In this manual, integer usually means a multiple precision integer, as
defined by the GMP 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 a 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.
There are six classes of functions in the GMP library:
mpz_. The associated type is mpz_t. There are about 100
functions in this class.
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.
mpf_. The associated type is mpf_t. There are about 50
functions is this class.
itom, madd, and
mult. The associated type is MINT.
mpn_. There are about 30 (hard-to-use) functions in this class.
The associated type is array of mp_limb_t.
As a general rule, all GMP 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.)
GMP lets you use the same variable for both input and output in one call. For
example, the main function for integer multiplication, mpz_mul, can be
used to square x and put the result back in x with
mpz_mul (x, x, x);
Before you can assign to a GMP 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 initializing and clearing out a GMP variable in a loop. Instead, initialize it before entering the loop, and clear it out after the loop has exited.
GMP variables are small, containing only a couple of sizes, and pointers to allocated data. Once you have initialized a GMP variable, you don't need to worry about space allocation. All functions in GMP automatically allocate additional space when a variable does not already have enough. They do not, however, reduce the space when a smaller value is stored. Most of the time this policy is best, since it avoids frequent re-allocation.
When a variable of type mpz_t is used as a function parameter, it's
effectively a call-by-reference, meaning anything the function does to it will
be be done to the original in the caller. When a function is going to return
an mpz_t result, it should provide a separate parameter or parameters
that it sets, like the GMP library functions do. A return of an
mpz_t doesn't return the object, only a pointer to it, and this is
almost certainly not what you want. All this applies to mpq_t and
mpf_t too.
Here's an example function accepting an mpz_t parameter, doing a
certain calculation, and returning a result.
void
myfunction (mpz_t result, mpz_t param, unsigned long n)
{
unsigned long i;
mpz_mul_ui (result, param, n);
for (i = 1; i < n; i++)
mpz_add_ui (result, result, i*7);
}
int
main (void)
{
mpz_t r, n;
mpz_init (r);
mpz_init_set_str (n, "123456", 0);
myfunction (r, n, 20L);
mpz_out_str (stdout, 10, r); printf ("\n");
return 0;
}
This example will work if result and param are the same
variable, just like the library functions. But sometimes this is tricky to
arrange, and an application might not want to bother for its own subroutines.
mpz_t is actually implemented as a one-element array of a certain
structure type. This is why using it to declare a variable gives an object
with the fields GMP needs, but then using it as a parameter passes a pointer
to the object. Note that the actual contents of an mpz_t are for
internal use only and you should not access them directly if you want your
code to be compatible with future GMP releases.
The GMP code is reentrant and thread-safe, with some exceptions:
mpf_set_default_prec saves the selected precision in
a global variable.
mp_set_memory_functions uses several global
variables for storing the selected memory allocation functions.
mp_set_memory_functions (or malloc and friends by default) are
not reentrant, GMP will not be reentrant either.
mpz_random, etc) use a random number
generator from the C library, usually mrand48 or random. These
routines are not reentrant, since they rely on global state.
(However the newer random number functions that accept a
gmp_randstate_t parameter are reentrant.)
alloca is not available, or GMP is configured with
`--disable-alloca', the library is not reentrant, due to the current
implementation of `stack-alloc.c'. In the generated `config.h',
USE_STACK_ALLOC set to 1 will mean not reentrant.
This version of GMP is upwardly binary compatible with versions 3.0 and 3.0.1, and upwardly compatible at the source level with versions 2.0, 2.0.1, and 2.0.2, with the following exceptions.
mpn_gcd had its source arguments swapped as of GMP 3.0 for consistency
with other mpn functions.
mpf_get_prec counted precision slightly differently in GMP 3.0 and
3.0.1, but in 3.1 has reverted to the 2.0.x style.
There are a number of compatibility issues between GMP 1 and GMP 2 that of course also apply when porting applications from GMP 1 to GMP 3. Please see the GMP 2 manual for details.
The latest version of the GMP library is available at ftp://ftp.gnu.org/pub/gnu/gmp. Many sites around the world mirror `ftp.gnu.org'; please use a mirror site near you, see http://www.gnu.org/order/ftp.html.
Go to the first, previous, next, last section, table of contents.