(gmp.info.gz) Integer Import and Export
Info Catalog
(gmp.info.gz) Integer Random Numbers
(gmp.info.gz) Integer Functions
(gmp.info.gz) Miscellaneous Integer Functions
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, int
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];
mpz_t z;
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,
int SIZE, int ENDIAN, size_t NAILS, 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 ( 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. ( Integer Comparisons)
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);
Info Catalog
(gmp.info.gz) Integer Random Numbers
(gmp.info.gz) Integer Functions
(gmp.info.gz) Miscellaneous Integer Functions
automatically generated byinfo2html