GNU Info

(gmp.info)Initializing Integers

---

Next: Assigning Integers Prev: Integer Functions Up: Integer Functions

---

Enter node , (file) or (file)node

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 INTEGER)
     Initialize INTEGER, and set its value to 0.

 - Function: void mpz_init2 (mpz_t INTEGER, unsigned long N)
     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.

 - Function: void mpz_clear (mpz_t INTEGER)
     Free the space occupied by INTEGER.  Call this function for all
     `mpz_t' variables when you are done with them.

 - Function: void mpz_realloc2 (mpz_t INTEGER, unsigned long N)
     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.

 - Function: void mpz_array_init (mpz_t INTEGER_ARRAY[], size_t
          ARRAY_SIZE, mp_size_t FIXED_NUM_BITS)
     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'!

 - Function: void * _mpz_realloc (mpz_t INTEGER, mp_size_t NEW_ALLOC)
     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.