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

Function: void mpz_init (mpz_t x)

Initialize x, and set its value to 0.

Function: void mpz_inits (mpz_t x, ...)

Initialize a NULL-terminated list of mpz_t variables, and set their values to 0.

Function: void mpz_init2 (mpz_t x, mp_bitcnt_t n)

Initialize x, with space for n-bit numbers, and set its value to 0. Calling this function instead of mpz_init or mpz_inits is never necessary; reallocation is handled automatically by GMP when needed.

While n defines the initial space, x 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.

In preparation for an operation, GMP often allocates one limb more than ultimately needed. To make sure GMP will not perform reallocation for x, you need to add the number of bits in mp_limb_t to n.

Function: void mpz_clear (mpz_t x)

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

Function: void mpz_clears (mpz_t x, ...)

Free the space occupied by a NULL-terminated list of mpz_t variables.

Function: void mpz_realloc2 (mpz_t x, mp_bitcnt_t n)

Change the space allocated for x to n bits. The value in x is preserved if it fits, or is set to 0 if not.

Calling this function is never necessary; reallocation is handled automatically by GMP when needed. But 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.