Node:Initializing Integers, Next:Assigning Integers, Previous:Integer Functions, Up:Integer Functions

Initialization Functions

The functions for integer arithmetic assume that all integer objects are initialized. You do that by calling the function mpz_init. For example,

{
  mpz_t integ;
  mpz_init (integ);
  ...
  mpz_add (integ, ...);
  ...
  mpz_sub (integ, ...);

  /* Unless the program is about to exit, do ... */
  mpz_clear (integ);
}

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

void mpz_init (mpz_t integer)

Function

Initialize integer, and set its value to 0.

void mpz_init2 (mpz_t integer, unsigned long n)

Function

Initialize integer, with space for n bits, and set its value to 0. n is only the initial space, integer will grow automatically in the normal way, if necessary, for subsequent values stored. mpz_init2 makes it possible to avoid such reallocations if a maximum size is known in advance.

void mpz_clear (mpz_t integer)

Function

Free the space occupied by integer. Call this function for all mpz_t variables when you are done with them.

void mpz_realloc2 (mpz_t integer, unsigned long n)

Function

Change the space allocated for integer to n bits. The value in integer is preserved if it fits, or is set to 0 if not. This function can be used to increase the space for a variable in order to avoid repeated automatic reallocations, or to decrease it to give memory back to the heap.

void mpz_array_init (mpz_t integer_array[], size_t array_size, mp_size_t fixed_num_bits)

Function

This is a special type of initialization. Fixed space of fixed_num_bits bits is allocated to each of the array_size integers in integer_array. The space will not be automatically increased, unlike the normal mpz_init, but instead an application must ensure it's sufficient for any value stored. The following space requirements apply to various functions, mpz_abs, mpz_neg, mpz_set, mpz_set_si and mpz_set_ui need room for the value they store. mpz_add, mpz_add_ui, mpz_sub and mpz_sub_ui need room for the larger of the two operands, plus an extra mp_bits_per_limb. mpz_mul, mpz_mul_ui and mpz_mul_ui need room for the sum of the number of bits in their operands, but each rounded up to a multiple of mp_bits_per_limb. mpz_swap can be used between two array variables, but not between an array and a normal variable. For other functions, or if in doubt, the suggestion is to calculate in a regular mpz_init variable and copy the result to an array variable with mpz_set. mpz_array_init can reduce memory usage in algorithms that need large arrays of integers, since it avoids allocating and reallocating lots of small memory blocks. There is no way to free the storage allocated by this function. Don't call mpz_clear!

void * _mpz_realloc (mpz_t integer, mp_size_t new_alloc)

Function

Change the space for integer to new_alloc limbs. The value in integer is preserved if it fits, or is set to 0 if not. The return value is not useful to applications and should be ignored. mpz_realloc2 is the preferred way to accomplish allocation changes like this. mpz_realloc2 and _mpz_realloc are the same except that _mpz_realloc takes the new size in limbs.