DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

(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