Integer Import and Export (GNU MP 6.3.0)
Description: How to install and use the GNU multiple precision arithmetic library, version 6.3.0.

### 5.14 Integer Import and Export ¶

`mpz_t` variables can be converted to and from arbitrary words of binary data with the following functions.

Function: `void` mpz_import `(mpz_t rop, size_t count, int order, size_t size, int endian, size_t nails, const void *op)` ¶

  Set rop from an array of word data at op.

  The parameters specify the format of the data. count many words are read, each size bytes. order can be 1 for most significant word first or -1 for least significant first. Within each word endian can be 1 for most significant byte first, -1 for least significant first, or 0 for the native endianness of the host CPU. The most significant nails bits of each word are skipped, this can be 0 to use the full words.

  There is no sign taken from the data, rop will simply be a positive integer. An application can handle any sign itself, and apply it for instance with `mpz_neg`.

  There are no data alignment restrictions on op, any address is allowed.

  Here’s an example converting an array of `unsigned long` data, most significant element first, and host byte order within each value.

      unsigned long  a[20];
      /* Initialize z and a */
      mpz_import (z, 20, 1, sizeof(a[0]), 0, 0, a);

  This example assumes the full `sizeof` bytes are used for data in the given type, which is usually true, and certainly true for `unsigned long` everywhere we know of. However on Cray vector systems it may be noted that `short` and `int` are always stored in 8 bytes (and with `sizeof` indicating that) but use only 32 or 46 bits. The nails feature can account for this, by passing for instance `8*sizeof(int)-INT_BIT`.

Function: `void *` mpz_export `(void *rop, size_t *countp, int order, size_t size, int endian, size_t nails, const mpz_t op)` ¶

  Fill rop with word data from op.

  The parameters specify the format of the data produced. Each word will be size bytes and order can be 1 for most significant word first or -1 for least significant first. Within each word endian can be 1 for most significant byte first, -1 for least significant first, or 0 for the native endianness of the host CPU. The most significant nails bits of each word are unused and set to zero, this can be 0 to produce full words.

  The number of words produced is written to `*countp`, or countp can be `NULL` to discard the count. rop must have enough space for the data, or if rop is `NULL` then a result array of the necessary size is allocated using the current GMP allocation function (see Custom Allocation). In either case the return value is the destination used, either rop or the allocated block.

  If op is non-zero then the most significant word produced will be non-zero. If op is zero then the count returned will be zero and nothing written to rop. If rop is `NULL` in this case, no block is allocated, just `NULL` is returned.

  The sign of op is ignored, just the absolute value is exported. An application can use `mpz_sgn` to get the sign and handle it as desired. (see Comparison Functions)

  There are no data alignment restrictions on rop, any address is allowed.

  When an application is allocating space itself the required size can be determined with a calculation like the following. Since `mpz_sizeinbase` always returns at least 1, `count` here will be at least one, which avoids any portability problems with `malloc(0)`, though if `z` is zero no space at all is actually needed (or written).

      numb = 8*size - nail;
      count = (mpz_sizeinbase (z, 2) + numb-1) / numb;
      p = malloc (count * size);