5.16 Special Functions

The functions in this section are for various special purposes. Most applications will not need them.

Function: void mpz_array_init (mpz_t integer_array, mp_size_t array_size, mp_size_t fixed_num_bits)

This is an obsolete function. Do not use it.

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 its size in limbs.

Function: mp_limb_t mpz_getlimbn (const mpz_t op, mp_size_t n)

Return limb number n from op. The sign of op is ignored, just the absolute value is used. The least significant limb is number 0.

mpz_size can be used to find how many limbs make up op. mpz_getlimbn returns zero if n is outside the range 0 to mpz_size(op)-1.

Function: size_t mpz_size (const mpz_t op)

Return the size of op measured in number of limbs. If op is zero, the returned value will be zero.

Function: const mp_limb_t * mpz_limbs_read (const mpz_t x)

Return a pointer to the limb array representing the absolute value of x. The size of the array is mpz_size(x). Intended for read access only.

Function: mp_limb_t * mpz_limbs_write (mpz_t x, mp_size_t n)

Function: mp_limb_t * mpz_limbs_modify (mpz_t x, mp_size_t n)

Return a pointer to the limb array, intended for write access. The array is reallocated as needed, to make room for n limbs. Requires n > 0. The mpz_limbs_modify function returns an array that holds the old absolute value of x, while mpz_limbs_write may destroy the old value and return an array with unspecified contents.

Function: void mpz_limbs_finish (mpz_t x, mp_size_t s)

Updates the internal size field of x. Used after writing to the limb array pointer returned by mpz_limbs_write or mpz_limbs_modify is completed. The array should contain abs(s) valid limbs, representing the new absolute value for x, and the sign of x is taken from the sign of s. This function never reallocates x, so the limb pointer remains valid.

void foo (mpz_t x)
{
  mp_size_t n, i;
  mp_limb_t *xp;

  n = mpz_size (x);
  xp = mpz_limbs_modify(x, 2*n);
  for (i = 0; i < n; i++)
    xp[n+i] = xp[n-1-i];
  mpz_limbs_finish (x, mpz_sgn (x) < 0 ? - 2*n : 2*n);
}

Function: mpz_srcptr mpz_roinit_n (mpz_t x, const mp_limb_t *xp, mp_size_t xs)

Special initialization of x, using the given limb array and size. x should be treated as read-only: it can be passed safely as input to any mpz function, but not as an output. The array xp must point to at least a readable limb, its size is abs(xs), and the sign of x is the sign of xs. For convenience, the function returns x, but cast to a const pointer type.

void foo (mpz_t x)
{
  static const mp_limb_t y[3] = { 0x1, 0x2, 0x3 };
  mpz_t tmp;
  mpz_add (x, x, mpz_roinit_n (tmp, y, 3));
}

Macro: mpz_t MPZ_ROINIT_N (mp_limb_t *xp, mp_size_t xs)

This macro expands to an initializer which can be assigned to an mpz_t variable. The limb array xp must point to at least a readable limb, moreover, unlike the mpz_roinit_n function, the array must be normalized: if xs is non-zero, then xp[abs(xs)-1] must be non-zero. Intended primarily for constant values. Using it for non-constant values requires a C compiler supporting C99.

void foo (mpz_t x)
{
  static const mp_limb_t ya[3] = { 0x1, 0x2, 0x3 };
  static const mpz_t y = MPZ_ROINIT_N ((mp_limb_t *) ya, 3);

  mpz_add (x, x, y);
}