Go to the previous, next section.

This chapter describes the MP functions for performing integer arithmetic.

The integer functions use arguments and values of type
pointer-to-`MP_INT`

(see section Nomenclature and Data Types). The type `MP_INT`

is a structure, but applications should not refer directly to its
components. Include the header ``gmp.h'` to get the definition of
`MP_INT`

.

Most of the functions for integer arithmetic assume that the output is
stored in an object already initialized. For example, `mpz_add`

stores the result of addition (see section Integer Arithmetic Functions). Thus, you
must initialize the object before storing the first value in it. You
can do this separately by calling the function `mpz_init`

.

__Function:__ void **mpz_init** *(MP_INT * integer)*

Initialize `integer` with limb space and set the initial numeric
value to 0. Each variable should normally only be initialized once,
or at least cleared out (using `mpz_clear`

) between each initialization.

Here is an example of using `mpz_init`

:

{ MP_INT integ; mpz_init (&integ); ... mpz_add (&integ, ...); ... mpz_sub (&integ, ...); /* Unless you are now exiting the program, do ... */ mpz_clear (&integ); }

As you can see, you can store new values any number of times, once an object is initialized.

__Function:__ void **mpz_clear** *(MP_INT * integer)*

Free the limb space occupied by `integer`. Make sure to call this
function for all `MP_INT`

variables when you are done with them.

__Function:__ void * **_mpz_realloc** *(MP_INT * integer, mp_size new_alloc)*

Change the limb space allocation to `new_alloc` limbs. This
function is not normally called from user code, but it can be used to
give memory back to the heap, or to increase the space of a variable to
avoid repeated automatic re-allocation.

__Function:__ void **mpz_array_init** *(MP_INT integer_array[], size_t array_size, mp_size fixed_num_limbs)*

Allocate **fixed** limb space for all `array_size` integers in
`integer_array`. The fixed allocation for each integer in the array
is `fixed_num_limbs`. This function is useful for decreasing the
working set for some algorithms that use large integer arrays. If the
fixed space will be insufficient for storing the result of a subsequent
calculation, the result is unpredictable.

There is no way to de-allocate the storage allocated by this function. Don't
call `mpz_clear`

!

These functions assign new values to already initialized integers (see section Initializing Integer Objects).

__Function:__ void **mpz_set** *(MP_INT * dest_integer, MP_INT *src_integer)*

Assign `dest_integer` from `src_integer`.

__Function:__ void **mpz_set_ui** *(MP_INT * integer, unsigned long int initial_value)*

Set the value of `integer` from `initial_value`.

__Function:__ void **mpz_set_si** *(MP_INT * integer, signed long int initial_value)*

Set the value of `integer` from `initial_value`.

__Function:__ int **mpz_set_str** *(MP_INT * integer, char *initial_value, int base)*

Set the value of `integer` from `initial_value`,
a '\0'-terminated C string in base `base`. White space is allowed in
the string, and is simply ignored. The base may vary from 2 to 36. If
`base` is 0, the actual base is determined from the leading characters: if
the first two characters are `0x' or `0X', hexadecimal is assumed,
otherwise if the first character is `0', octal is assumed, otherwise
decimal is assumed.

This function returns 0 if the entire string up to the '\0' is a valid
number in base `base`. Otherwise it returns -1.

For your convenience, MP provides a parallel series of
initialize-and-set arithmetic functions which initialize the output and
then store the value there. These functions' names have the form
`mpz_init_set...`

.

Here is an example of using one:

{ MP_INT integ; mpz_init_set_str (&integ, "3141592653589793238462643383279502884", 10); ... mpz_sub (&integ, ...); mpz_clear (&integ); }

Once the integer has been initialized by any of the
`mpz_init_set...`

functions, it can be used as the source or
destination operand for the ordinary integer functions. Don't use an
initialize-and-set function on a variable already initialized!

__Function:__ void **mpz_init_set** *(MP_INT * dest_integer, MP_INT *src_integer)*

Initialize `dest_integer` with limb space and set the initial numeric
value from `src_integer`.

__Function:__ void **mpz_init_set_ui** *(MP_INT * dest_integer, unsigned long int src_ulong)*

Initialize `dest_integer` with limb space and set the initial numeric
value from `src_ulong`.

__Function:__ void **mpz_init_set_si** *(MP_INT * dest_integer, signed long int src_slong)*

Initialize `dest_integer` with limb space and set the initial numeric
value from `src_slong`.

__Function:__ int **mpz_init_set_str** *(MP_INT * dest_integer, char *src_cstring, int base)*

Initialize `dest_integer` with limb space and set the initial
numeric value from `src_cstring`, a '\0'-terminated C string in base
`base`. The base may vary from 2 to 36. There may be white space
in the string.

If the string is a correct base `base` number, the function returns
0; if an error occurs it returns -1. `dest_integer` is
initialized even if an error occurs. (I.e., you have to call mpz_clear
for it.)

__Function:__ unsigned long int **mpz_get_ui** *(MP_INT * src_integer)*

Return the least significant limb from `src_integer`. This
function together with

`mpz_div_2exp(..., `

can be used to extract the limbs of an integer efficiently.
`src_integer`, CHAR_BIT*sizeof(unsigned
long int))

__Function:__ signed long int **mpz_get_si** *(MP_INT * src_integer)*

If `src_integer` fits into a `signed long int`

return the value
of `src_integer`. Otherwise return the least significant bits of
`src_integer`, with the same sign as `src_integer`.

__Function:__ char * **mpz_get_str** *(char * string, int base, MP_INT *integer)*

Convert `integer` to a '\0'-terminated C string in `string`,
using base `base`. The base may vary from 2 to 36. If `string`
is NULL, space for the string is allocated using the default allocation
function.

If `string` is not NULL, it should point to a block of storage
enough large for the result. To find out the right amount of space to
provide for `string`, use `mpz_sizeinbase (`

. The "+ 2" is for a possible minus sign, and for the
terminating null character. (see section Miscellaneous Functions).
`integer`,
`base`) + 2

This function returns a pointer to the result string.

__Function:__ void **mpz_add** *(MP_INT * sum, MP_INT *addend1, MP_INT *addend2)*

__Function:__ void **mpz_add_ui** *(MP_INT * sum, MP_INT *addend1, unsigned long int addend2)*

Set `sum` to `addend1` + `addend2`.

__Function:__ void **mpz_sub** *(MP_INT * difference, MP_INT *minuend, MP_INT *subtrahend)*

__Function:__ void **mpz_sub_ui** *(MP_INT * difference, MP_INT *minuend, unsigned long int subtrahend)*

Set `difference` to `minuend` - `subtrahend`.

__Function:__ void **mpz_mul** *(MP_INT * product, MP_INT *multiplicator, MP_INT *multiplicand)*

__Function:__ void **mpz_mul_ui** *(MP_INT * product, MP_INT *multiplicator, unsigned long int multiplicand)*

Set `product` to `multiplicator` times `multiplicand`.

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

__Function:__ void **mpz_div** *(MP_INT * quotient, MP_INT *dividend, MP_INT *divisor)*

__Function:__ void **mpz_div_ui** *(MP_INT * quotient, MP_INT *dividend, unsigned long int divisor)*

Set `quotient` to `dividend` / `divisor`. The quotient is
rounded towards 0.

__Function:__ void **mpz_mod** *(MP_INT * remainder, MP_INT *divdend, MP_INT *divisor)*

__Function:__ void **mpz_mod_ui** *(MP_INT * remainder, MP_INT *divdend, unsigned long int divisor)*

Divide `dividend` and `divisor` and put the remainder in
`remainder`. The remainder has the same sign as the dividend, and
its absolute value is less than the absolute value of the divisor.

__Function:__ void **mpz_divmod** *(MP_INT * quotient, MP_INT *remainder, MP_INT *dividend, MP_INT *divisor)*

__Function:__ void **mpz_divmod_ui** *(MP_INT * quotient, MP_INT *remainder, MP_INT *dividend, unsigned long int divisor)*

Divide `dividend` and `divisor` and put the quotient in
`quotient` and the remainder in `remainder`. The quotient is
rounded towards 0. The remainder has the same sign as the dividend,
and its absolute value is less than the absolute value of the divisor.

If `quotient` and `remainder` are the same variable, the results
are not defined.

__Function:__ void **mpz_mdiv** *(MP_INT * quotient, MP_INT *dividend, MP_INT *divisor)*

__Function:__ void **mpz_mdiv_ui** *(MP_INT * quotient, MP_INT *dividend, unsigned long int divisor)*

Set `quotient` to `dividend` / `divisor`. The quotient is
rounded towards -infinity.

__Function:__ void **mpz_mmod** *(MP_INT * remainder, MP_INT *divdend, MP_INT *divisor)*

__Function:__ unsigned long int **mpz_mmod_ui** *(MP_INT * remainder, MP_INT *divdend, unsigned long int divisor)*

Divide `dividend` and `divisor` and put the remainder in
`remainder`. The remainder is always positive, and its value is
less than the value of the divisor.

For `mpz_mmod_ui`

the remainder is returned, and if `remainder` is
not NULL, also stored there.

__Function:__ void **mpz_mdivmod** *(MP_INT * quotient, MP_INT *remainder, MP_INT *dividend, MP_INT *divisor)*

__Function:__ unsigned long int **mpz_mdivmod_ui** *(MP_INT * quotient, MP_INT *remainder, MP_INT *dividend, unsigned long int divisor)*

Divide `dividend` and `divisor` and put the quotient in
`quotient` and the remainder in `remainder`. The quotient is
rounded towards -infinity. The remainder is always positive, and its
value is less than the value of the divisor.

For `mpz_mdivmod_ui`

the remainder is small enough to fit in an
`unsigned long int`

, and is therefore returned. If `remainder`
is not NULL, the remainder is also stored there.

If `quotient` and `remainder` are the same variable, the results
are not defined.

__Function:__ void **mpz_sqrt** *(MP_INT * root, MP_INT *operand)*

Set `root` to the square root of `operand`. The result is
rounded towards zero.

__Function:__ void **mpz_sqrtrem** *(MP_INT * root, MP_INT *remainder, MP_INT *operand)*

Set `root` to the square root of `operand`, as with
`mpz_sqrt`

. Set `remainder` to
(i.e. zero if `operand` is a perfect square).

If `root` and `remainder` are the same variable, the results are
not defined.

__Function:__ int **mpz_perfect_square_p** *(MP_INT * square)*

Return non-zero if `square` is perfect, i.e. if the square root of
`square` is integral. Return zero otherwise.

__Function:__ int **mpz_probab_prime_p** *(MP_INT * n, int reps)*

An implementation of the probabilistic primality test found in Knuth's
Seminumerical Algorithms book. If the function
`mpz_probab_prime_p(`

returns 0 then `n`, `reps`)`n` is
not prime. If it returns 1, then `n` is `probably' prime. The
probability of a false positive is (1/4)**`reps`, where `reps`
is the number of internal passes of the probabilistic algorithm. Knuth
indicates that 25 passes are reasonable.

__Function:__ void **mpz_powm** *(MP_INT * res, MP_INT *base, MP_INT *exp, MP_INT *mod)*

__Function:__ void **mpz_powm_ui** *(MP_INT * res, MP_INT *base, unsigned long int exp, MP_INT *mod)*

Set `res` to (`base` raised to `exp`) modulo `mod`.
If `exp` is negative, the result is undefined.

__Function:__ void **mpz_pow_ui** *(MP_INT * res, MP_INT *base, unsigned long int exp)*

Set `res` to `base` raised to `exp`.

__Function:__ void **mpz_fac_ui** *(MP_INT * res, unsigned long int n)*

Set `res` `n`!, the factorial of n.

__Function:__ void **mpz_gcd** *(MP_INT * res, MP_INT *operand1, MP_INT *operand2)*

Set `res` to the greatest common divisor of `operand1` and
`operand2`.

__Function:__ void **mpz_gcdext** *(MP_INT * g, MP_INT *s, MP_INT *t, MP_INT *a, MP_INT *b)*

Compute `g`, `s`, and `t`, such that `a``s` +
`b``t` = `g` = `gcd`

(`a`, `b`). If `t` is
NULL, that argument is not computed.

__Function:__ void **mpz_neg** *(MP_INT * negated_operand, MP_INT *operand)*

Set `negated_operand` to -`operand`.

__Function:__ void **mpz_abs** *(MP_INT * positive_operand, MP_INT *signed_operand)*

Set `positive_operand` to the absolute value of `signed_operand`.

__Function:__ int **mpz_cmp** *(MP_INT * operand1, MP_INT *operand2)*

__Function:__ int **mpz_cmp_ui** *(MP_INT * operand1, unsigned long int operand2)*

__Function:__ int **mpz_cmp_si** *(MP_INT * operand1, signed long int operand2)*

Compare `operand1` and `operand2`. Return a positive value if
`operand1` > `operand2`, zero if `operand1` = `operand2`,
and a negative value if `operand1` < `operand2`.

__Function:__ void **mpz_mul_2exp** *(MP_INT * product, MP_INT *multiplicator, unsigned long int exponent_of_2)*

Set `product` to `multiplicator` times 2 raised to
`exponent_of_2`. This operation can also be defined as a left shift,
`exponent_of_2` steps.

__Function:__ void **mpz_div_2exp** *(MP_INT * quotient, MP_INT *dividend, unsigned long int exponent_of_2)*

Set `quotient` to `dividend` divided by 2 raised to
`exponent_of_2`. This operation can also be defined as a right
shift, `exponent_of_2` steps, but unlike the >> operator in
C, the result is rounded towards 0.

__Function:__ void **mpz_mod_2exp** *(MP_INT * remainder, MP_INT *dividend, unsigned long int exponent_of_2)*

Set `remainder` to `dividend` mod (2 raised to
`exponent_of_2`). The sign of `remainder` will have the same sign
as `dividend`.

This operation can also be defined as a masking of the
`exponent_of_2` least significant bits.

__Function:__ void **mpz_and** *(MP_INT * conjunction, MP_INT *operand1, MP_INT *operand2)*

Set `conjunction` to `operand1` logical-and `operand2`.

__Function:__ void **mpz_ior** *(MP_INT * disjunction, MP_INT *operand1, MP_INT *operand2)*

Set `disjunction` to `operand1` inclusive-or `operand2`.

__Function:__ void **mpz_xor** *(MP_INT * disjunction, MP_INT *operand1, MP_INT *operand2)*

Set `disjunction` to `operand1` exclusive-or `operand2`.

This function is missing in the current release.

__Function:__ void **mpz_com** *(MP_INT * complemented_operand, MP_INT *operand)*

Set `complemented_operand` to the one's complement of `operand`.

Functions that perform input from a standard I/O stream, and functions for output conversion.

__Function:__ void **mpz_inp_raw** *(MP_INT * integer, FILE *stream)*

Input from standard I/O stream `stream` in the format written by
`mpz_out_raw`

, and put the result in `integer`.

__Function:__ void **mpz_inp_str** *(MP_INT * integer, FILE *stream, int base)*

Input a string in base `base` from standard I/O stream `stream`,
and put the read integer in `integer`. The base may vary from 2 to
36. If `base` is 0, the actual base is determined from the leading
characters: if the first two characters are `0x' or `0X', hexadecimal is
assumed, otherwise if the first character is `0', octal is assumed,
otherwise decimal is assumed.

__Function:__ void **mpz_out_raw** *(FILE * stream, MP_INT *integer)*

Output `integer` on standard I/O stream `stream`, in raw binary
format. The integer is written in a portable format, with 4 bytes of
size information, and that many bytes of limbs. Both the size and the
limbs are written in decreasing significance order.

__Function:__ void **mpz_out_str** *(FILE * stream, int base, MP_INT *integer)*

Output `integer` on standard I/O stream `stream`, as a string of
digits in base `base`. The base may vary from 2 to 36.

Go to the previous, next section.