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(..., src_integer, CHAR_BIT*sizeof(unsigned
long int)) can be used to extract the limbs of an integer efficiently.
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 (integer,
base) + 2. The "+ 2" is for a possible minus sign, and for the
terminating null character. (see section Miscellaneous Functions).
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(n, reps) returns 0 then 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 as +
bt = 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.