[BACK]Return to gmp.info-2 CVS log [TXT][DIR] Up to [local] / OpenXM_contrib / gmp

Diff for /OpenXM_contrib/gmp/Attic/gmp.info-2 between version 1.1.1.1 and 1.1.1.4

version 1.1.1.1, 2000/01/10 15:35:21 version 1.1.1.4, 2003/08/25 16:06:02
Line 1 
Line 1 
 This is Info file gmp.info, produced by Makeinfo-1.64 from the input  This is gmp.info, produced by makeinfo version 4.2 from gmp.texi.
 file gmp.texi.  
   
   This manual describes how to install and use the GNU multiple precision
   arithmetic library, version 4.1.2.
   
      Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
   2001, 2002 Free Software Foundation, Inc.
   
      Permission is granted to copy, distribute and/or modify this
   document under the terms of the GNU Free Documentation License, Version
   1.1 or any later version published by the Free Software Foundation;
   with no Invariant Sections, with the Front-Cover Texts being "A GNU
   Manual", and with the Back-Cover Texts being "You have freedom to copy
   and modify this GNU Manual, like GNU software".  A copy of the license
   is included in *Note GNU Free Documentation License::.
   INFO-DIR-SECTION GNU libraries
 START-INFO-DIR-ENTRY  START-INFO-DIR-ENTRY
 * gmp: (gmp.info).               GNU Multiple Precision Arithmetic Library.  * gmp: (gmp).                   GNU Multiple Precision Arithmetic Library.
 END-INFO-DIR-ENTRY  END-INFO-DIR-ENTRY
   
    This file documents GNU MP, a library for arbitrary-precision  
 arithmetic.  File: gmp.info,  Node: Parameter Conventions,  Next: Memory Management,  Prev: Variable Conventions,  Up: GMP Basics
   
    Copyright (C) 1991, 1993, 1994, 1995, 1996 Free Software Foundation,  Parameter Conventions
 Inc.  =====================
   
    Permission is granted to make and distribute verbatim copies of this     When a GMP variable is used as a function parameter, it's
 manual provided the copyright notice and this permission notice are  effectively a call-by-reference, meaning if the function stores a value
 preserved on all copies.  there it will change the original in the caller.  Parameters which are
   input-only can be designated `const' to provoke a compiler error or
   warning on attempting to modify them.
   
    Permission is granted to copy and distribute modified versions of     When a function is going to return a GMP result, it should designate
 this manual under the conditions for verbatim copying, provided that  a parameter that it sets, like the library functions do.  More than one
 the entire resulting derived work is distributed under the terms of a  value can be returned by having more than one output parameter, again
 permission notice identical to this one.  like the library functions.  A `return' of an `mpz_t' etc doesn't
   return the object, only a pointer, and this is almost certainly not
   what's wanted.
   
    Permission is granted to copy and distribute translations of this     Here's an example accepting an `mpz_t' parameter, doing a
 manual into another language, under the above conditions for modified  calculation, and storing the result to the indicated parameter.
 versions, except that this permission notice may be stated in a  
 translation approved by the Foundation.  
   
        void
        foo (mpz_t result, const mpz_t param, unsigned long n)
        {
          unsigned long  i;
          mpz_mul_ui (result, param, n);
          for (i = 1; i < n; i++)
            mpz_add_ui (result, result, i*7);
        }
   
        int
        main (void)
        {
          mpz_t  r, n;
          mpz_init (r);
          mpz_init_set_str (n, "123456", 0);
          foo (r, n, 20L);
          gmp_printf ("%Zd\n", r);
          return 0;
        }
   
      `foo' works even if the mainline passes the same variable for
   `param' and `result', just like the library functions.  But sometimes
   it's tricky to make that work, and an application might not want to
   bother supporting that sort of thing.
   
      For interest, the GMP types `mpz_t' etc are implemented as
   one-element arrays of certain structures.  This is why declaring a
   variable creates an object with the fields GMP needs, but then using it
   as a parameter passes a pointer to the object.  Note that the actual
   fields in each `mpz_t' etc are for internal use only and should not be
   accessed directly by code that expects to be compatible with future GMP
   releases.
   
   
 File: gmp.info,  Node: Floating-point Functions,  Next: Low-level Functions,  Prev: Rational Number Functions,  Up: Top  File: gmp.info,  Node: Memory Management,  Next: Reentrancy,  Prev: Parameter Conventions,  Up: GMP Basics
   
 Floating-point Functions  Memory Management
 ************************  =================
   
    This is a description of the *preliminary* interface for     The GMP types like `mpz_t' are small, containing only a couple of
 floating-point arithmetic in GNU MP 2.  sizes, and pointers to allocated data.  Once a variable is initialized,
   GMP takes care of all space allocation.  Additional space is allocated
   whenever a variable doesn't have enough.
   
    The floating-point functions expect arguments of type `mpf_t'.     `mpz_t' and `mpq_t' variables never reduce their allocated space.
   Normally this is the best policy, since it avoids frequent reallocation.
   Applications that need to return memory to the heap at some particular
   point can use `mpz_realloc2', or clear variables no longer needed.
   
    The MP floating-point functions have an interface that is similar to     `mpf_t' variables, in the current implementation, use a fixed amount
 the MP integer functions.  The function prefix for floating-point  of space, determined by the chosen precision and allocated at
 operations is `mpf_'.  initialization, so their size doesn't change.
   
    There is one significant characteristic of floating-point numbers     All memory is allocated using `malloc' and friends by default, but
 that has motivated a difference between this function class and other  this can be changed, see *Note Custom Allocation::.  Temporary memory
 MP function classes: the inherent inexactness of floating point  on the stack is also used (via `alloca'), but this can be changed at
 arithmetic.  The user has to specify the precision of each variable.  A  build-time if desired, see *Note Build Options::.
 computation that assigns a variable will take place with the precision  
 of the assigned variable; the precision of variables used as input is  
 ignored.  
   
    The precision of a calculation is defined as follows: Compute the  
 requested operation exactly (with "infinite precision"), and truncate  File: gmp.info,  Node: Reentrancy,  Next: Useful Macros and Constants,  Prev: Memory Management,  Up: GMP Basics
 the result to the destination variable precision.  Even if the user has  
 asked for a very high precision, MP will not calculate with superfluous  
 digits.  For example, if two low-precision numbers of nearly equal  
 magnitude are added, the precision of the result will be limited to  
 what is required to represent the result accurately.  
   
    The MP floating-point functions are *not* intended as a smooth  Reentrancy
 extension to the IEEE P754 arithmetic.  Specifically, the results  ==========
 obtained on one computer often differs from the results obtained on a  
 computer with a different word size.  
   
 * Menu:     GMP is reentrant and thread-safe, with some exceptions:
   
 * Initializing Floats::     * If configured with `--enable-alloca=malloc-notreentrant' (or with
 * Assigning Floats::       `--enable-alloca=notreentrant' when `alloca' is not available),
 * Simultaneous Float Init & Assign::       then naturally GMP is not reentrant.
 * Converting Floats::  
 * Float Arithmetic::  
 * Float Comparison::  
 * I/O of Floats::  
 * Miscellaneous Float Functions::  
   
      * `mpf_set_default_prec' and `mpf_init' use a global variable for the
 File: gmp.info,  Node: Initializing Floats,  Next: Assigning Floats,  Up: Floating-point Functions       selected precision.  `mpf_init2' can be used instead.
   
 Initialization and Assignment Functions     * `mpz_random' and the other old random number functions use a global
 =======================================       random state and are hence not reentrant.  The newer random number
        functions that accept a `gmp_randstate_t' parameter can be used
        instead.
   
  - Function: void mpf_set_default_prec (unsigned long int PREC)     * `mp_set_memory_functions' uses global variables to store the
      Set the default precision to be *at least* PREC bits.  All       selected memory allocation functions.
      subsequent calls to `mpf_init' will use this precision, but  
      previously initialized variables are unaffected.  
   
    An `mpf_t' object must be initialized before storing the first value     * If the memory allocation functions set by a call to
 in it.  The functions `mpf_init' and `mpf_init2' are used for that       `mp_set_memory_functions' (or `malloc' and friends by default) are
 purpose.       not reentrant, then GMP will not be reentrant either.
   
  - Function: void mpf_init (mpf_t X)     * If the standard I/O functions such as `fwrite' are not reentrant
      Initialize X to 0.  Normally, a variable should be initialized       then the GMP I/O functions using them will not be reentrant either.
      once only or at least be cleared, using `mpf_clear', between  
      initializations.  The precision of X is undefined unless a default  
      precision has already been established by a call to  
      `mpf_set_default_prec'.  
   
  - Function: void mpf_init2 (mpf_t X, unsigned long int PREC)     * It's safe for two threads to read from the same GMP variable
      Initialize X to 0 and set its precision to be *at least* PREC       simultaneously, but it's not safe for one to read while the
      bits.  Normally, a variable should be initialized once only or at       another might be writing, nor for two threads to write
      least be cleared, using `mpf_clear', between initializations.       simultaneously.  It's not safe for two threads to generate a
        random number from the same `gmp_randstate_t' simultaneously,
        since this involves an update of that variable.
   
  - Function: void mpf_clear (mpf_t X)     * On SCO systems the default `<ctype.h>' macros use per-file static
      Free the space occupied by X.  Make sure to call this function for       variables and may not be reentrant, depending whether the compiler
      all `mpf_t' variables when you are done with them.       optimizes away fetches from them.  The GMP text-based input
        functions are affected.
   
    Here is an example on how to initialize floating-point variables:  
      {  File: gmp.info,  Node: Useful Macros and Constants,  Next: Compatibility with older versions,  Prev: Reentrancy,  Up: GMP Basics
        mpf_t x, y;  
        mpf_init (x);                    /* use default precision */  
        mpf_init2 (y, 256);              /* precision *at least* 256 bits */  
        ...  
        /* Unless the program is about to exit, do ... */  
        mpf_clear (x);  
        mpf_clear (y);  
      }  
   
    The following three functions are useful for changing the precision  Useful Macros and Constants
 during a calculation.  A typical use would be for adjusting the  ===========================
 precision gradually in iterative algorithms like Newton-Raphson, making  
 the computation precision closely match the actual accurate part of the  
 numbers.  
   
  - Function: void mpf_set_prec (mpf_t ROP, unsigned long int PREC)   - Global Constant: const int mp_bits_per_limb
      Set the precision of ROP to be *at least* PREC bits.  Since       The number of bits per limb.
      changing the precision involves calls to `realloc', this routine  
      should not be called in a tight loop.  
   
  - Function: unsigned long int mpf_get_prec (mpf_t OP)   - Macro: __GNU_MP_VERSION
      Return the precision actually used for assignments of OP.   - Macro: __GNU_MP_VERSION_MINOR
    - Macro: __GNU_MP_VERSION_PATCHLEVEL
        The major and minor GMP version, and patch level, respectively, as
        integers.  For GMP i.j, these numbers will be i, j, and 0,
        respectively.  For GMP i.j.k, these numbers will be i, j, and k,
        respectively.
   
  - Function: void mpf_set_prec_raw (mpf_t ROP, unsigned long int PREC)   - Global Constant: const char * const gmp_version
      Set the precision of ROP to be *at least* PREC bits.  This is a       The GMP version number, as a null-terminated string, in the form
      low-level function that does not change the allocation.  The PREC       "i.j" or "i.j.k".  This release is "4.1.2".
      argument must not be larger that the precision previously returned  
      by `mpf_get_prec'.  It is crucial that the precision of ROP is  
      ultimately reset to exactly the value returned by `mpf_get_prec'.  
   
   
 File: gmp.info,  Node: Assigning Floats,  Next: Simultaneous Float Init & Assign,  Prev: Initializing Floats,  Up: Floating-point Functions  File: gmp.info,  Node: Compatibility with older versions,  Next: Demonstration Programs,  Prev: Useful Macros and Constants,  Up: GMP Basics
   
 Assignment Functions  Compatibility with older versions
 --------------------  =================================
   
    These functions assign new values to already initialized floats     This version of GMP is upwardly binary compatible with all 4.x and
 (*note Initializing Floats::.).  3.x versions, and upwardly compatible at the source level with all 2.x
   versions, with the following exceptions.
   
  - Function: void mpf_set (mpf_t ROP, mpf_t OP)     * `mpn_gcd' had its source arguments swapped as of GMP 3.0, for
  - Function: void mpf_set_ui (mpf_t ROP, unsigned long int OP)       consistency with other `mpn' functions.
  - Function: void mpf_set_si (mpf_t ROP, signed long int OP)  
  - Function: void mpf_set_d (mpf_t ROP, double OP)  
  - Function: void mpf_set_z (mpf_t ROP, mpz_t OP)  
  - Function: void mpf_set_q (mpf_t ROP, mpq_t OP)  
      Set the value of ROP from OP.  
   
  - Function: int mpf_set_str (mpf_t ROP, char *STR, int BASE)     * `mpf_get_prec' counted precision slightly differently in GMP 3.0
      Set the value of ROP from the string in STR.  The string is of the       and 3.0.1, but in 3.1 reverted to the 2.x style.
      form `M@N' or, if the base is 10 or less, alternatively `MeN'.  
      `M' is the mantissa and `N' is the exponent.  The mantissa is  
      always in the specified base.  The exponent is either in the  
      specified base or, if BASE is negative, in decimal.  
   
      The argument BASE may be in the ranges 2 to 36, or -36 to -2.     There are a number of compatibility issues between GMP 1 and GMP 2
      Negative values are used to specify that the exponent is in  that of course also apply when porting applications from GMP 1 to GMP
      decimal.  4.  Please see the GMP 2 manual for details.
   
      Unlike the corresponding `mpz' function, the base will not be     The Berkeley MP compatibility library (*note BSD Compatible
      determined from the leading characters of the string if BASE is 0.  Functions::) is source and binary compatible with the standard `libmp'.
      This is so that numbers like `0.23' are not interpreted as octal.  
   
      White space is allowed in the string, and is simply ignored.  
   File: gmp.info,  Node: Demonstration Programs,  Next: Efficiency,  Prev: Compatibility with older versions,  Up: GMP Basics
   
      This function returns 0 if the entire string up to the '\0' is a  Demonstration programs
      valid number in base BASE.  Otherwise it returns -1.  ======================
   
      The `demos' subdirectory has some sample programs using GMP.  These
 File: gmp.info,  Node: Simultaneous Float Init & Assign,  Next: Converting Floats,  Prev: Assigning Floats,  Up: Floating-point Functions  aren't built or installed, but there's a `Makefile' with rules for them.
   For instance,
   
 Combined Initialization and Assignment Functions       make pexpr
 ------------------------------------------------       ./pexpr 68^975+10
   
    For convenience, MP provides a parallel series of initialize-and-set  The following programs are provided
 functions which initialize the output and then store the value there.  
 These functions' names have the form `mpf_init_set...'  
   
    Once the float has been initialized by any of the `mpf_init_set...'     * `pexpr' is an expression evaluator, the program used on the GMP
 functions, it can be used as the source or destination operand for the       web page.
 ordinary float functions.  Don't use an initialize-and-set function on  
 a variable already initialized!  
   
  - Function: void mpf_init_set (mpf_t ROP, mpf_t OP)     * The `calc' subdirectory has a similar but simpler evaluator using
  - Function: void mpf_init_set_ui (mpf_t ROP, unsigned long int OP)       `lex' and `yacc'.
  - Function: void mpf_init_set_si (mpf_t ROP, signed long int OP)  
  - Function: void mpf_init_set_d (mpf_t ROP, double OP)  
      Initialize ROP and set its value from OP.  
   
      The precision of ROP will be taken from the active default     * The `expr' subdirectory is yet another expression evaluator, a
      precision, as set by `mpf_set_default_prec'.       library designed for ease of use within a C program.  See
        `demos/expr/README' for more information.
   
  - Function: int mpf_init_set_str (mpf_t ROP, char *STR, int BASE)     * `factorize' is a Pollard-Rho factorization program.
      Initialize ROP and set its value from the string in STR.  See  
      `mpf_set_str' above for details on the assignment operation.  
   
      Note that ROP is initialized even if an error occurs.  (I.e., you     * `isprime' is a command-line interface to the `mpz_probab_prime_p'
      have to call `mpf_clear' for it.)       function.
   
      The precision of ROP will be taken from the active default     * `primes' counts or lists primes in an interval, using a sieve.
      precision, as set by `mpf_set_default_prec'.  
   
      * `qcn' is an example use of `mpz_kronecker_ui' to estimate quadratic
        class numbers.
   
      * The `perl' subdirectory is a comprehensive perl interface to GMP.
        See `demos/perl/INSTALL' for more information.  Documentation is
        in POD format in `demos/perl/GMP.pm'.
   
   
 File: gmp.info,  Node: Converting Floats,  Next: Float Arithmetic,  Prev: Simultaneous Float Init & Assign,  Up: Floating-point Functions  File: gmp.info,  Node: Efficiency,  Next: Debugging,  Prev: Demonstration Programs,  Up: GMP Basics
   
 Conversion Functions  Efficiency
 ====================  ==========
   
  - Function: double mpf_get_d (mpf_t OP)  Small operands
      Convert OP to a double.       On small operands, the time for function call overheads and memory
        allocation can be significant in comparison to actual calculation.
        This is unavoidable in a general purpose variable precision
        library, although GMP attempts to be as efficient as it can on
        both large and small operands.
   
  - Function: char * mpf_get_str (char *STR, mp_exp_t *EXPPTR, int BASE,  Static Linking
           size_t N_DIGITS, mpf_t OP)       On some CPUs, in particular the x86s, the static `libgmp.a' should
      Convert OP to a string of digits in base BASE.  The base may vary       be used for maximum speed, since the PIC code in the shared
      from 2 to 36.  Generate at most N_DIGITS significant digits, or if       `libgmp.so' will have a small overhead on each function call and
      N_DIGITS is 0, the maximum number of digits accurately       global data address.  For many programs this will be
      representable by OP.       insignificant, but for long calculations there's a gain to be had.
   
      If STR is NULL, space for the mantissa is allocated using the  Initializing and clearing
      default allocation function, and a pointer to the string is       Avoid excessive initializing and clearing of variables, since this
      returned.       can be quite time consuming, especially in comparison to otherwise
        fast operations like addition.
   
      If STR is not NULL, it should point to a block of storage enough       A language interpreter might want to keep a free list or stack of
      large for the mantissa, i.e., N_DIGITS + 2.  The two extra bytes       initialized variables ready for use.  It should be possible to
      are for a possible minus sign, and for the terminating null       integrate something like that with a garbage collector too.
      character.  
   
      The exponent is written through the pointer EXPPTR.  Reallocations
        An `mpz_t' or `mpq_t' variable used to hold successively increasing
        values will have its memory repeatedly `realloc'ed, which could be
        quite slow or could fragment memory, depending on the C library.
        If an application can estimate the final size then `mpz_init2' or
        `mpz_realloc2' can be called to allocate the necessary space from
        the beginning (*note Initializing Integers::).
   
      If N_DIGITS is 0, the maximum number of digits meaningfully       It doesn't matter if a size set with `mpz_init2' or `mpz_realloc2'
      achievable from the precision of OP will be generated.  Note that       is too small, since all functions will do a further reallocation
      the space requirements for STR in this case will be impossible for       if necessary.  Badly overestimating memory required will waste
      the user to predetermine.  Therefore, you need to pass NULL for       space though.
      the string argument whenever N_DIGITS is 0.  
   
      The generated string is a fraction, with an implicit radix point  `2exp' functions
      immediately to the left of the first digit.  For example, the       It's up to an application to call functions like `mpz_mul_2exp'
      number 3.1416 would be returned as "31416" in the string and 1       when appropriate.  General purpose functions like `mpz_mul' make
      written at EXPPTR.       no attempt to identify powers of two or other special forms,
        because such inputs will usually be very rare and testing every
        time would be wasteful.
   
   `ui' and `si' functions
 File: gmp.info,  Node: Float Arithmetic,  Next: Float Comparison,  Prev: Converting Floats,  Up: Floating-point Functions       The `ui' functions and the small number of `si' functions exist for
        convenience and should be used where applicable.  But if for
        example an `mpz_t' contains a value that fits in an `unsigned
        long' there's no need extract it and call a `ui' function, just
        use the regular `mpz' function.
   
 Arithmetic Functions  In-Place Operations
 ====================       `mpz_abs', `mpq_abs', `mpf_abs', `mpz_neg', `mpq_neg' and
        `mpf_neg' are fast when used for in-place operations like
        `mpz_abs(x,x)', since in the current implementation only a single
        field of `x' needs changing.  On suitable compilers (GCC for
        instance) this is inlined too.
   
  - Function: void mpf_add (mpf_t ROP, mpf_t OP1, mpf_t OP2)       `mpz_add_ui', `mpz_sub_ui', `mpf_add_ui' and `mpf_sub_ui' benefit
  - Function: void mpf_add_ui (mpf_t ROP, mpf_t OP1, unsigned long int       from an in-place operation like `mpz_add_ui(x,x,y)', since usually
           OP2)       only one or two limbs of `x' will need to be changed.  The same
      Set ROP to OP1 + OP2.       applies to the full precision `mpz_add' etc if `y' is small.  If
        `y' is big then cache locality may be helped, but that's all.
   
  - Function: void mpf_sub (mpf_t ROP, mpf_t OP1, mpf_t OP2)       `mpz_mul' is currently the opposite, a separate destination is
  - Function: void mpf_ui_sub (mpf_t ROP, unsigned long int OP1, mpf_t       slightly better.  A call like `mpz_mul(x,x,y)' will, unless `y' is
           OP2)       only one limb, make a temporary copy of `x' before forming the
  - Function: void mpf_sub_ui (mpf_t ROP, mpf_t OP1, unsigned long int       result.  Normally that copying will only be a tiny fraction of the
           OP2)       time for the multiply, so this is not a particularly important
      Set ROP to OP1 - OP2.       consideration.
   
  - Function: void mpf_mul (mpf_t ROP, mpf_t OP1, mpf_t OP2)       `mpz_set', `mpq_set', `mpq_set_num', `mpf_set', etc, make no
  - Function: void mpf_mul_ui (mpf_t ROP, mpf_t OP1, unsigned long int       attempt to recognise a copy of something to itself, so a call like
           OP2)       `mpz_set(x,x)' will be wasteful.  Naturally that would never be
      Set ROP to OP1 times OP2.       written deliberately, but if it might arise from two pointers to
        the same object then a test to avoid it might be desirable.
   
    Division is undefined if the divisor is zero, and passing a zero            if (x != y)
 divisor to the divide functions will make these functions intentionally              mpz_set (x, y);
 divide by zero.  This gives the user the possibility to handle  
 arithmetic exceptions in these functions in the same manner as other  
 arithmetic exceptions.  
   
  - Function: void mpf_div (mpf_t ROP, mpf_t OP1, mpf_t OP2)       Note that it's never worth introducing extra `mpz_set' calls just
  - Function: void mpf_ui_div (mpf_t ROP, unsigned long int OP1, mpf_t       to get in-place operations.  If a result should go to a particular
           OP2)       variable then just direct it there and let GMP take care of data
  - Function: void mpf_div_ui (mpf_t ROP, mpf_t OP1, unsigned long int       movement.
           OP2)  
      Set ROP to OP1/OP2.  
   
  - Function: void mpf_sqrt (mpf_t ROP, mpf_t OP)  Divisibility Testing (Small Integers)
  - Function: void mpf_sqrt_ui (mpf_t ROP, unsigned long int OP)       `mpz_divisible_ui_p' and `mpz_congruent_ui_p' are the best
      Set ROP to the square root of OP.       functions for testing whether an `mpz_t' is divisible by an
        individual small integer.  They use an algorithm which is faster
        than `mpz_tdiv_ui', but which gives no useful information about
        the actual remainder, only whether it's zero (or a particular
        value).
   
  - Function: void mpf_neg (mpf_t ROP, mpf_t OP)       However when testing divisibility by several small integers, it's
      Set ROP to -OP.       best to take a remainder modulo their product, to save
        multi-precision operations.  For instance to test whether a number
        is divisible by any of 23, 29 or 31 take a remainder modulo
        23*29*31 = 20677 and then test that.
   
  - Function: void mpf_abs (mpf_t ROP, mpf_t OP)       The division functions like `mpz_tdiv_q_ui' which give a quotient
      Set ROP to the absolute value of OP.       as well as a remainder are generally a little slower than the
        remainder-only functions like `mpz_tdiv_ui'.  If the quotient is
        only rarely wanted then it's probably best to just take a
        remainder and then go back and calculate the quotient if and when
        it's wanted (`mpz_divexact_ui' can be used if the remainder is
        zero).
   
  - Function: void mpf_mul_2exp (mpf_t ROP, mpf_t OP1, unsigned long int  Rational Arithmetic
           OP2)       The `mpq' functions operate on `mpq_t' values with no common
      Set ROP to OP1 times 2 raised to OP2.       factors in the numerator and denominator.  Common factors are
        checked-for and cast out as necessary.  In general, cancelling
        factors every time is the best approach since it minimizes the
        sizes for subsequent operations.
   
  - Function: void mpf_div_2exp (mpf_t ROP, mpf_t OP1, unsigned long int       However, applications that know something about the factorization
           OP2)       of the values they're working with might be able to avoid some of
      Set ROP to OP1 divided by 2 raised to OP2.       the GCDs used for canonicalization, or swap them for divisions.
        For example when multiplying by a prime it's enough to check for
        factors of it in the denominator instead of doing a full GCD.  Or
        when forming a big product it might be known that very little
        cancellation will be possible, and so canonicalization can be left
        to the end.
   
        The `mpq_numref' and `mpq_denref' macros give access to the
        numerator and denominator to do things outside the scope of the
        supplied `mpq' functions.  *Note Applying Integer Functions::.
   
        The canonical form for rationals allows mixed-type `mpq_t' and
        integer additions or subtractions to be done directly with
        multiples of the denominator.  This will be somewhat faster than
        `mpq_add'.  For example,
   
             /* mpq increment */
             mpz_add (mpq_numref(q), mpq_numref(q), mpq_denref(q));
   
             /* mpq += unsigned long */
             mpz_addmul_ui (mpq_numref(q), mpq_denref(q), 123UL);
   
             /* mpq -= mpz */
             mpz_submul (mpq_numref(q), mpq_denref(q), z);
   
   Number Sequences
        Functions like `mpz_fac_ui', `mpz_fib_ui' and `mpz_bin_uiui' are
        designed for calculating isolated values.  If a range of values is
        wanted it's probably best to call to get a starting point and
        iterate from there.
   
   Text Input/Output
        Hexadecimal or octal are suggested for input or output in text
        form.  Power-of-2 bases like these can be converted much more
        efficiently than other bases, like decimal.  For big numbers
        there's usually nothing of particular interest to be seen in the
        digits, so the base doesn't matter much.
   
        Maybe we can hope octal will one day become the normal base for
        everyday use, as proposed by King Charles XII of Sweden and later
        reformers.
   
   
 File: gmp.info,  Node: Float Comparison,  Next: I/O of Floats,  Prev: Float Arithmetic,  Up: Floating-point Functions  File: gmp.info,  Node: Debugging,  Next: Profiling,  Prev: Efficiency,  Up: GMP Basics
   
 Comparison Functions  Debugging
 ====================  =========
   
  - Function: int mpf_cmp (mpf_t OP1, mpf_t OP2)  Stack Overflow
  - Function: int mpf_cmp_ui (mpf_t OP1, unsigned long int OP2)       Depending on the system, a segmentation violation or bus error
  - Function: int mpf_cmp_si (mpf_t OP1, signed long int OP2)       might be the only indication of stack overflow.  See
      Compare OP1 and OP2.  Return a positive value if OP1 > OP2, zero       `--enable-alloca' choices in *Note Build Options::, for how to
      if OP1 = OP2, and a negative value if OP1 < OP2.       address this.
   
  - Function: int mpf_eq (mpf_t OP1, mpf_t OP2, unsigned long int op3)       In new enough versions of GCC, `-fstack-check' may be able to
      Return non-zero if the first OP3 bits of OP1 and OP2 are equal,       ensure an overflow is recognised by the system before too much
      zero otherwise.  I.e., test of OP1 and OP2 are approximately equal.       damage is done, or `-fstack-limit-symbol' or
        `-fstack-limit-register' may be able to add checking if the system
        itself doesn't do any (*note Options for Code Generation:
        (gcc)Code Gen Options.).  These options must be added to the
        `CFLAGS' used in the GMP build (*note Build Options::), adding
        them just to an application will have no effect.  Note also
        they're a slowdown, adding overhead to each function call and each
        stack allocation.
   
  - Function: void mpf_reldiff (mpf_t ROP, mpf_t OP1, mpf_t OP2)  Heap Problems
      Compute the relative difference between OP1 and OP2 and store the       The most likely cause of application problems with GMP is heap
      result in ROP.       corruption.  Failing to `init' GMP variables will have
        unpredictable effects, and corruption arising elsewhere in a
        program may well affect GMP.  Initializing GMP variables more than
        once or failing to clear them will cause memory leaks.
   
  - Macro: int mpf_sgn (mpf_t OP)       In all such cases a malloc debugger is recommended.  On a GNU or
      Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.       BSD system the standard C library `malloc' has some diagnostic
        facilities, see *Note Allocation Debugging: (libc)Allocation
        Debugging, or `man 3 malloc'.  Other possibilities, in no
        particular order, include
   
      This function is actually implemented as a macro.  It evaluates its            `http://www.inf.ethz.ch/personal/biere/projects/ccmalloc'
      arguments multiple times.            `http://quorum.tamu.edu/jon/gnu'  (debauch)
             `http://dmalloc.com'
             `http://www.perens.com/FreeSoftware'  (electric fence)
             `http://packages.debian.org/fda'
             `http://www.gnupdate.org/components/leakbug'
             `http://people.redhat.com/~otaylor/memprof'
             `http://www.cbmamiga.demon.co.uk/mpatrol'
   
        The GMP default allocation routines in `memory.c' also have a
 File: gmp.info,  Node: I/O of Floats,  Next: Miscellaneous Float Functions,  Prev: Float Comparison,  Up: Floating-point Functions       simple sentinel scheme which can be enabled with `#define DEBUG'
        in that file.  This is mainly designed for detecting buffer
        overruns during GMP development, but might find other uses.
   
 Input and Output Functions  Stack Backtraces
 ==========================       On some systems the compiler options GMP uses by default can
        interfere with debugging.  In particular on x86 and 68k systems
        `-fomit-frame-pointer' is used and this generally inhibits stack
        backtracing.  Recompiling without such options may help while
        debugging, though the usual caveats about it potentially moving a
        memory problem or hiding a compiler bug will apply.
   
    Functions that perform input from a stdio stream, and functions that  GNU Debugger
 output to a stdio stream.  Passing a NULL pointer for a STREAM argument       A sample `.gdbinit' is included in the distribution, showing how
 to any of these functions will make them read from `stdin' and write to       to call some undocumented dump functions to print GMP variables
 `stdout', respectively.       from within GDB.  Note that these functions shouldn't be used in
        final application code since they're undocumented and may be
        subject to incompatible changes in future versions of GMP.
   
    When using any of these functions, it is a good idea to include  Source File Paths
 `stdio.h' before `gmp.h', since that will allow `gmp.h' to define       GMP has multiple source files with the same name, in different
 prototypes for these functions.       directories.  For example `mpz', `mpq', `mpf' and `mpfr' each have
        an `init.c'.  If the debugger can't already determine the right
        one it may help to build with absolute paths on each C file.  One
        way to do that is to use a separate object directory with an
        absolute path to the source directory.
   
  - Function: size_t mpf_out_str (FILE *STREAM, int BASE, size_t            cd /my/build/dir
           N_DIGITS, mpf_t OP)            /my/source/dir/gmp-4.1.2/configure
      Output OP on stdio stream STREAM, as a string of digits in base  
      BASE.  The base may vary from 2 to 36.  Print at most N_DIGITS  
      significant digits, or if N_DIGITS is 0, the maximum number of  
      digits accurately representable by OP.  
   
      In addition to the significant digits, a leading `0.' and a       This works via `VPATH', and might require GNU `make'.  Alternately
      trailing exponent, in the form `eNNN', are printed.  If BASE is       it might be possible to change the `.c.lo' rules appropriately.
      greater than 10, `@' will be used instead of `e' as exponent  
      delimiter.  
   
      Return the number of bytes written, or if an error occurred,  Assertion Checking
      return 0.       The build option `--enable-assert' is available to add some
        consistency checks to the library (see *Note Build Options::).
        These are likely to be of limited value to most applications.
        Assertion failures are just as likely to indicate memory
        corruption as a library or compiler bug.
   
  - Function: size_t mpf_inp_str (mpf_t ROP, FILE *STREAM, int BASE)       Applications using the low-level `mpn' functions, however, will
      Input a string in base BASE from stdio stream STREAM, and put the       benefit from `--enable-assert' since it adds checks on the
      read float in ROP.  The string is of the form `M@N' or, if the       parameters of most such functions, many of which have subtle
      base is 10 or less, alternatively `MeN'.  `M' is the mantissa and       restrictions on their usage.  Note however that only the generic C
      `N' is the exponent.  The mantissa is always in the specified       code has checks, not the assembler code, so CPU `none' should be
      base.  The exponent is either in the specified base or, if BASE is       used for maximum checking.
      negative, in decimal.  
   
      The argument BASE may be in the ranges 2 to 36, or -36 to -2.  Temporary Memory Checking
      Negative values are used to specify that the exponent is in       The build option `--enable-alloca=debug' arranges that each block
      decimal.       of temporary memory in GMP is allocated with a separate call to
        `malloc' (or the allocation function set with
        `mp_set_memory_functions').
   
      Unlike the corresponding `mpz' function, the base will not be       This can help a malloc debugger detect accesses outside the
      determined from the leading characters of the string if BASE is 0.       intended bounds, or detect memory not released.  In a normal
      This is so that numbers like `0.23' are not interpreted as octal.       build, on the other hand, temporary memory is allocated in blocks
        which GMP divides up for its own use, or may be allocated with a
        compiler builtin `alloca' which will go nowhere near any malloc
        debugger hooks.
   
      Return the number of bytes read, or if an error occurred, return 0.  Maximum Debuggability
        To summarize the above, a GMP build for maximum debuggability
        would be
   
             ./configure --disable-shared --enable-assert \
 File: gmp.info,  Node: Miscellaneous Float Functions,  Prev: I/O of Floats,  Up: Floating-point Functions              --enable-alloca=debug --host=none CFLAGS=-g
   
 Miscellaneous Functions       For C++, add `--enable-cxx CXXFLAGS=-g'.
 =======================  
   
  - Function: void mpf_random2 (mpf_t ROP, mp_size_t MAX_SIZE, mp_exp_t  Checker
           MAX_EXP)       The checker program (`http://savannah.gnu.org/projects/checker')
      Generate a random float of at most MAX_SIZE limbs, with long       can be used with GMP.  It contains a stub library which means GMP
      strings of zeros and ones in the binary representation.  The       applications compiled with checker can use a normal GMP build.
      exponent of the number is in the interval -EXP to EXP.  This  
      function is useful for testing functions and algorithms, since  
      this kind of random numbers have proven to be more likely to  
      trigger corner-case bugs.  Negative random numbers are generated  
      when MAX_SIZE is negative.  
   
        A build of GMP with checking within GMP itself can be made.  This
        will run very very slowly.  Configure with
   
             ./configure --host=none-pc-linux-gnu CC=checkergcc
   
        `--host=none' must be used, since the GMP assembler code doesn't
        support the checking scheme.  The GMP C++ features cannot be used,
        since current versions of checker (0.9.9.1) don't yet support the
        standard C++ library.
   
   Valgrind
        The valgrind program (`http://devel-home.kde.org/~sewardj') is a
        memory checker for x86s.  It translates and emulates machine
        instructions to do strong checks for uninitialized data (at the
        level of individual bits), memory accesses through bad pointers,
        and memory leaks.
   
        Current versions (20020226 snapshot) don't support MMX or SSE, so
        GMP must be configured for an x86 without those (eg. plain
        `i386'), or with a special `MPN_PATH' that excludes those
        subdirectories (*note Build Options::).
   
   Other Problems
        Any suspected bug in GMP itself should be isolated to make sure
        it's not an application problem, see *Note Reporting Bugs::.
   
   
 File: gmp.info,  Node: Low-level Functions,  Next: BSD Compatible Functions,  Prev: Floating-point Functions,  Up: Top  File: gmp.info,  Node: Profiling,  Next: Autoconf,  Prev: Debugging,  Up: GMP Basics
   
 Low-level Functions  Profiling
 *******************  =========
   
    This chapter describes low-level MP functions, used to implement the     Running a program under a profiler is a good way to find where it's
 high-level MP functions, but also intended for time-critical user code.  spending most time and where improvements can be best sought.
   
    These functions start with the prefix `mpn_'.     Depending on the system, it may be possible to get a flat profile,
   meaning simple timer sampling of the program counter, with no special
   GMP build options, just a `-p' when compiling the mainline.  This is a
   good way to ensure minimum interference with normal operation.  The
   necessary symbol type and size information exists in most of the GMP
   assembler code.
   
    The `mpn' functions are designed to be as fast as possible, *not* to     The `--enable-profiling' build option can be used to add suitable
 provide a coherent calling interface.  The different functions have  compiler flags, either for `prof' (`-p') or `gprof' (`-pg'), see *Note
 somewhat similar interfaces, but there are variations that make them  Build Options::.  Which of the two is available and what they do will
 hard to use.  These functions do as little as possible apart from the  depend on the system, and possibly on support available in `libc'.  For
 real multiple precision computation, so that no time is spent on things  some systems appropriate corresponding `mcount' calls are added to the
 that not all callers need.  assembler code too.
   
    A source operand is specified by a pointer to the least significant     On x86 systems `prof' gives call counting, so that average time spent
 limb and a limb count.  A destination operand is specified by just a  in a function can be determined.  `gprof', where supported, adds call
 pointer.  It is the responsibility of the caller to ensure that the  graph construction, so for instance calls to `mpn_add_n' from `mpz_add'
 destination has enough space for storing the result.  and from `mpz_mul' can be differentiated.
   
    With this way of specifying operands, it is possible to perform     On x86 and 68k systems `-pg' and `-fomit-frame-pointer' are
 computations on subranges of an argument, and store the result into a  incompatible, so the latter is not used when `gprof' profiling is
 subrange of a destination.  selected, which may result in poorer code generation.  If `prof'
   profiling is selected instead it should still be possible to use
   `gprof', but only the `gprof -p' flat profile and call counts can be
   expected to be valid, not the `gprof -q' call graph.
   
    A common requirement for all functions is that each source area  
 needs at least one limb.  No size argument may be zero.  File: gmp.info,  Node: Autoconf,  Next: Emacs,  Prev: Profiling,  Up: GMP Basics
   
    The `mpn' functions is the base for the implementation of the `mpz_',  Autoconf
 `mpf_', and `mpq_' functions.  ========
   
    This example adds the number beginning at SRC1_PTR and the number     Autoconf based applications can easily check whether GMP is
 beginning at SRC2_PTR and writes the sum at DEST_PTR.  All areas have  installed.  The only thing to be noted is that GMP library symbols from
 SIZE limbs.  version 3 onwards have prefixes like `__gmpz'.  The following therefore
   would be a simple test,
   
      cy = mpn_add_n (dest_ptr, src1_ptr, src2_ptr, size)       AC_CHECK_LIB(gmp, __gmpz_init)
   
 In the notation used here, a source operand is identified by the     This just uses the default `AC_CHECK_LIB' actions for found or not
 pointer to the least significant limb, and the limb count in braces.  found, but an application that must have GMP would want to generate an
 For example, {s1_ptr, s1_size}.  error if not found.  For example,
   
  - Function: mp_limb_t mpn_add_n (mp_limb_t * DEST_PTR, const mp_limb_t       AC_CHECK_LIB(gmp, __gmpz_init, , [AC_MSG_ERROR(
           * SRC1_PTR, const mp_limb_t * SRC2_PTR, mp_size_t SIZE)       [GNU MP not found, see http://swox.com/gmp])])
      Add {SRC1_PTR, SIZE} and {SRC2_PTR, SIZE}, and write the SIZE  
      least significant limbs of the result to DEST_PTR.  Return carry,  
      either 0 or 1.  
   
      This is the lowest-level function for addition.  It is the     If functions added in some particular version of GMP are required,
      preferred function for addition, since it is written in assembly  then one of those can be used when checking.  For example `mpz_mul_si'
      for most targets.  For addition of a variable to itself (i.e.,  was added in GMP 3.1,
      SRC1_PTR equals SRC2_PTR, use `mpn_lshift' with a count of 1 for  
      optimal speed.  
   
  - Function: mp_limb_t mpn_add_1 (mp_limb_t * DEST_PTR, const mp_limb_t       AC_CHECK_LIB(gmp, __gmpz_mul_si, , [AC_MSG_ERROR(
           * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB)       [GNU MP not found, or not 3.1 or up, see http://swox.com/gmp])])
      Add {SRC1_PTR, SIZE} and SRC2_LIMB, and write the SIZE least  
      significant limbs of the result to DEST_PTR.  Return carry, either  
      0 or 1.  
   
  - Function: mp_limb_t mpn_add (mp_limb_t * DEST_PTR, const mp_limb_t *     An alternative would be to test the version number in `gmp.h' using
           SRC1_PTR, mp_size_t SRC1_SIZE, const mp_limb_t * SRC2_PTR,  say `AC_EGREP_CPP'.  That would make it possible to test the exact
           mp_size_t SRC2_SIZE)  version, if some particular sub-minor release is known to be necessary.
      Add {SRC1_PTR, SRC1_SIZE} and {SRC2_PTR, SRC2_SIZE}, and write the  
      SRC1_SIZE least significant limbs of the result to DEST_PTR.  
      Return carry, either 0 or 1.  
   
      This function requires that SRC1_SIZE is greater than or equal to     An application that can use either GMP 2 or 3 will need to test for
      SRC2_SIZE.  `__gmpz_init' (GMP 3 and up) or `mpz_init' (GMP 2), and it's also worth
   checking for `libgmp2' since Debian GNU/Linux systems used that name in
   the past.  For example,
   
  - Function: mp_limb_t mpn_sub_n (mp_limb_t * DEST_PTR, const mp_limb_t       AC_CHECK_LIB(gmp, __gmpz_init, ,
           * SRC1_PTR, const mp_limb_t * SRC2_PTR, mp_size_t SIZE)         [AC_CHECK_LIB(gmp, mpz_init, ,
      Subtract {SRC2_PTR, SRC2_SIZE} from {SRC1_PTR, SIZE}, and write           [AC_CHECK_LIB(gmp2, mpz_init)])])
      the SIZE least significant limbs of the result to DEST_PTR.  
      Return borrow, either 0 or 1.  
   
      This is the lowest-level function for subtraction.  It is the     In general it's suggested that applications should simply demand a
      preferred function for subtraction, since it is written in  new enough GMP rather than trying to provide supplements for features
      assembly for most targets.  not available in past versions.
   
  - Function: mp_limb_t mpn_sub_1 (mp_limb_t * DEST_PTR, const mp_limb_t     Occasionally an application will need or want to know the size of a
           * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB)  type at configuration or preprocessing time, not just with `sizeof' in
      Subtract SRC2_LIMB from {SRC1_PTR, SIZE}, and write the SIZE least  the code.  This can be done in the normal way with `mp_limb_t' etc, but
      significant limbs of the result to DEST_PTR.  Return borrow,  GMP 4.0 or up is best for this, since prior versions needed certain
      either 0 or 1.  `-D' defines on systems using a `long long' limb.  The following would
   suit Autoconf 2.50 or up,
   
  - Function: mp_limb_t mpn_sub (mp_limb_t * DEST_PTR, const mp_limb_t *       AC_CHECK_SIZEOF(mp_limb_t, , [#include <gmp.h>])
           SRC1_PTR, mp_size_t SRC1_SIZE, const mp_limb_t * SRC2_PTR,  
           mp_size_t SRC2_SIZE)  
      Subtract {SRC2_PTR, SRC2_SIZE} from {SRC1_PTR, SRC1_SIZE}, and  
      write the SRC1_SIZE least significant limbs of the result to  
      DEST_PTR.  Return borrow, either 0 or 1.  
   
      This function requires that SRC1_SIZE is greater than or equal to     The optional `mpfr' functions are provided in a separate
      SRC2_SIZE.  `libmpfr.a', and this might be from GMP with `--enable-mpfr' or from
   MPFR installed separately.  Either way `libmpfr' depends on `libgmp',
   it doesn't stand alone.  Currently only a static `libmpfr.a' will be
   available, not a shared library, since upward binary compatibility is
   not guaranteed.
   
  - Function: void mpn_mul_n (mp_limb_t * DEST_PTR, const mp_limb_t *       AC_CHECK_LIB(mpfr, mpfr_add, , [AC_MSG_ERROR(
           SRC1_PTR, const mp_limb_t * SRC2_PTR, mp_size_t SIZE)       [Need MPFR either from GNU MP 4 or separate MPFR package.
      Multiply {SRC1_PTR, SIZE} and {SRC2_PTR, SIZE}, and write the       See http://www.mpfr.org or http://swox.com/gmp])
      *entire* result to DEST_PTR.  
   
      The destination has to have space for 2SIZE limbs, even if the  
      significant result might be one limb smaller.  File: gmp.info,  Node: Emacs,  Prev: Autoconf,  Up: GMP Basics
   
  - Function: mp_limb_t mpn_mul_1 (mp_limb_t * DEST_PTR, const mp_limb_t  Emacs
           * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB)  =====
      Multiply {SRC1_PTR, SIZE} and SRC2_LIMB, and write the SIZE least  
      significant limbs of the product to DEST_PTR.  Return the most  
      significant limb of the product.  
   
      This is a low-level function that is a building block for general     <C-h C-i> (`info-lookup-symbol') is a good way to find documentation
      multiplication as well as other operations in MP.  It is written  on C functions while editing (*note Info Documentation Lookup:
      in assembly for most targets.  (emacs)Info Lookup.).
   
      Don't call this function if SRC2_LIMB is a power of 2; use     The GMP manual can be included in such lookups by putting the
      `mpn_lshift' with a count equal to the logarithm of SRC2_LIMB  following in your `.emacs',
      instead, for optimal speed.  
   
  - Function: mp_limb_t mpn_addmul_1 (mp_limb_t * DEST_PTR, const       (eval-after-load "info-look"
           mp_limb_t * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB)         '(let ((mode-value (assoc 'c-mode (assoc 'symbol info-lookup-alist))))
      Multiply {SRC1_PTR, SIZE} and SRC2_LIMB, and add the SIZE least            (setcar (nthcdr 3 mode-value)
      significant limbs of the product to {DEST_PTR, SIZE} and write the                    (cons '("(gmp)Function Index" nil "^ -.* " "\\>")
      result to DEST_PTR DEST_PTR.  Return the most significant limb of                          (nth 3 mode-value)))))
      the product, plus carry-out from the addition.  
   
      This is a low-level function that is a building block for general     The same can be done for MPFR, with `(mpfr)' in place of `(gmp)'.
      multiplication as well as other operations in MP.  It is written  
      in assembly for most targets.  
   
  - Function: mp_limb_t mpn_submul_1 (mp_limb_t * DEST_PTR, const  
           mp_limb_t * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB)  File: gmp.info,  Node: Reporting Bugs,  Next: Integer Functions,  Prev: GMP Basics,  Up: Top
      Multiply {SRC1_PTR, SIZE} and SRC2_LIMB, and subtract the SIZE  
      least significant limbs of the product from {DEST_PTR, SIZE} and  
      write the result to DEST_PTR.  Return the most significant limb of  
      the product, minus borrow-out from the subtraction.  
   
      This is a low-level function that is a building block for general  Reporting Bugs
      multiplication and division as well as other operations in MP.  It  **************
      is written in assembly for most targets.  
   
  - Function: mp_limb_t mpn_mul (mp_limb_t * DEST_PTR, const mp_limb_t *     If you think you have found a bug in the GMP library, please
           SRC1_PTR, mp_size_t SRC1_SIZE, const mp_limb_t * SRC2_PTR,  investigate it and report it.  We have made this library available to
           mp_size_t SRC2_SIZE)  you, and it is not too much to ask you to report the bugs you find.
      Multiply {SRC1_PTR, SRC1_SIZE} and {SRC2_PTR, SRC2_SIZE}, and  
      write the result to DEST_PTR.  Return the most significant limb of  
      the result.  
   
      The destination has to have space for SRC1_SIZE + SRC1_SIZE limbs,     Before you report a bug, check it's not already addressed in *Note
      even if the result might be one limb smaller.  Known Build Problems::, or perhaps *Note Notes for Particular
   Systems::.  You may also want to check `http://swox.com/gmp/' for
   patches for this release.
   
      This function requires that SRC1_SIZE is greater than or equal to     Please include the following in any report,
      SRC2_SIZE.  The destination must be distinct from either input  
      operands.  
   
  - Function: mp_size_t mpn_divrem (mp_limb_t * R1P, mp_size_t XSIZE,     * The GMP version number, and if pre-packaged or patched then say so.
           mp_limb_t * RS2P, mp_size_t RS2SIZE, const mp_limb_t * S3P,  
           mp_size_t S3SIZE)  
      Divide {RS2P, RS2SIZE} by {S3P, S3SIZE}, and write the quotient at  
      R1P, with the exception of the most significant limb, which is  
      returned.  The remainder replaces the dividend at RS2P.  
   
      In addition to an integer quotient, XSIZE fraction limbs are     * A test program that makes it possible for us to reproduce the bug.
      developed, and stored after the integral limbs.  For most usages,       Include instructions on how to run the program.
      XSIZE will be zero.  
   
      It is required that RS2SIZE is greater than or equal to S3SIZE.     * A description of what is wrong.  If the results are incorrect, in
      It is required that the most significant bit of the divisor is set.       what way.  If you get a crash, say so.
   
      If the quotient is not needed, pass RS2P + S3SIZE as R1P.  Aside     * If you get a crash, include a stack backtrace from the debugger if
      from that special case, no overlap between arguments is permitted.       it's informative (`where' in `gdb', or `$C' in `adb').
   
      Return the most significant limb of the quotient, either 0 or 1.     * Please do not send core dumps, executables or `strace's.
   
      The area at R1P needs to be RS2SIZE - S3SIZE + XSIZE limbs large.     * The configuration options you used when building GMP, if any.
   
  - Function: mp_limb_t mpn_divrem_1 (mp_limb_t * R1P, mp_size_t XSIZE,     * The name of the compiler and its version.  For `gcc', get the
           mp_limb_t * S2P, mp_size_t S2SIZE, mp_limb_t S3LIMB)       version with `gcc -v', otherwise perhaps `what `which cc`', or
      Divide {S2P, S2SIZE} by S3LIMB, and write the quotient at R1P.       similar.
      Return the remainder.  
   
      In addition to an integer quotient, XSIZE fraction limbs are     * The output from running `uname -a'.
      developed, and stored after the integral limbs.  For most usages,  
      XSIZE will be zero.  
   
      The areas at R1P and S2P have to be identical or completely     * The output from running `./config.guess', and from running
      separate, not partially overlapping.       `./configfsf.guess' (might be the same).
   
  - Function: mp_size_t mpn_divmod (mp_limb_t * R1P, mp_limb_t * RS2P,     * If the bug is related to `configure', then the contents of
           mp_size_t RS2SIZE, const mp_limb_t * S3P, mp_size_t S3SIZE)       `config.log'.
      *This interface is obsolete.  It will disappear from future  
      releases.  Use `mpn_divrem' in its stead.*  
   
  - Function: mp_limb_t mpn_divmod_1 (mp_limb_t * R1P, mp_limb_t * S2P,     * If the bug is related to an `asm' file not assembling, then the
           mp_size_t S2SIZE, mp_limb_t S3LIMB)       contents of `config.m4' and the offending line or lines from the
      *This interface is obsolete.  It will disappear from future       temporary `mpn/tmp-<file>.s'.
      releases.  Use `mpn_divrem_1' in its stead.*  
   
  - Function: mp_limb_t mpn_mod_1 (mp_limb_t * S1P, mp_size_t S1SIZE,     Please make an effort to produce a self-contained report, with
           mp_limb_t S2LIMB)  something definite that can be tested or debugged.  Vague queries or
      Divide {S1P, S1SIZE} by S2LIMB, and return the remainder.  piecemeal messages are difficult to act on and don't help the
   development effort.
   
  - Function: mp_limb_t mpn_preinv_mod_1 (mp_limb_t * S1P, mp_size_t     It is not uncommon that an observed problem is actually due to a bug
           S1SIZE, mp_limb_t S2LIMB, mp_limb_t S3LIMB)  in the compiler; the GMP code tends to explore interesting corners in
      *This interface is obsolete.  It will disappear from future  compilers.
      releases.  Use `mpn_mod_1' in its stead.*  
   
  - Function: mp_limb_t mpn_bdivmod (mp_limb_t * DEST_PTR, mp_limb_t *     If your bug report is good, we will do our best to help you get a
           S1P, mp_size_t S1SIZE, const mp_limb_t * S2P, mp_size_t  corrected version of the library; if the bug report is poor, we won't
           S2SIZE, unsigned long int D)  do anything about it (except maybe ask you to send a better report).
      The function puts the low [D/BITS_PER_MP_LIMB] limbs of Q = {S1P,  
      S1SIZE}/{S2P, S2SIZE} mod 2^D at DEST_PTR, and returns the high D  
      mod BITS_PER_MP_LIMB bits of Q.  
   
      {S1P, S1SIZE} - Q * {S2P, S2SIZE} mod 2^(S1SIZE*BITS_PER_MP_LIMB)     Send your report to: <bug-gmp@gnu.org>.
      is placed at S1P.  Since the low [D/BITS_PER_MP_LIMB] limbs of  
      this difference are zero, it is possible to overwrite the low  
      limbs at S1P with this difference, provided DEST_PTR <= S1P.  
   
      This function requires that S1SIZE * BITS_PER_MP_LIMB >= D, and     If you think something in this manual is unclear, or downright
      that {S2P, S2SIZE} is odd.  incorrect, or if the language needs to be improved, please send a note
   to the same address.
   
      *This interface is preliminary.  It might change incompatibly in  
      future revisions.*  File: gmp.info,  Node: Integer Functions,  Next: Rational Number Functions,  Prev: Reporting Bugs,  Up: Top
   
  - Function: mp_limb_t mpn_lshift (mp_limb_t * DEST_PTR, const  Integer Functions
           mp_limb_t * SRC_PTR, mp_size_t SRC_SIZE, unsigned long int  *****************
           COUNT)  
      Shift {SRC_PTR, SRC_SIZE} COUNT bits to the left, and write the  
      SRC_SIZE least significant limbs of the result to DEST_PTR.  COUNT  
      might be in the range 1 to n - 1, on an n-bit machine. The bits  
      shifted out to the left are returned.  
   
      Overlapping of the destination space and the source space is     This chapter describes the GMP functions for performing integer
      allowed in this function, provided DEST_PTR >= SRC_PTR.  arithmetic.  These functions start with the prefix `mpz_'.
   
      This function is written in assembly for most targets.     GMP integers are stored in objects of type `mpz_t'.
   
  - Function: mp_limp_t mpn_rshift (mp_limb_t * DEST_PTR, const  * Menu:
           mp_limb_t * SRC_PTR, mp_size_t SRC_SIZE, unsigned long int  
           COUNT)  
      Shift {SRC_PTR, SRC_SIZE} COUNT bits to the right, and write the  
      SRC_SIZE most significant limbs of the result to DEST_PTR.  COUNT  
      might be in the range 1 to n - 1, on an n-bit machine.  The bits  
      shifted out to the right are returned.  
   
      Overlapping of the destination space and the source space is  * Initializing Integers::
      allowed in this function, provided DEST_PTR <= SRC_PTR.  * Assigning Integers::
   * Simultaneous Integer Init & Assign::
   * Converting Integers::
   * Integer Arithmetic::
   * Integer Division::
   * Integer Exponentiation::
   * Integer Roots::
   * Number Theoretic Functions::
   * Integer Comparisons::
   * Integer Logic and Bit Fiddling::
   * I/O of Integers::
   * Integer Random Numbers::
   * Integer Import and Export::
   * Miscellaneous Integer Functions::
   
      This function is written in assembly for most targets.  
   File: gmp.info,  Node: Initializing Integers,  Next: Assigning Integers,  Prev: Integer Functions,  Up: Integer Functions
   
  - Function: int mpn_cmp (const mp_limb_t * SRC1_PTR, const mp_limb_t *  Initialization Functions
           SRC2_PTR, mp_size_t SIZE)  ========================
      Compare {SRC1_PTR, SIZE} and {SRC2_PTR, SIZE} and return a  
      positive value if src1 > src2, 0 of they are equal, and a negative  
      value if src1 < src2.  
   
  - Function: mp_size_t mpn_gcd (mp_limb_t * DEST_PTR, mp_limb_t *     The functions for integer arithmetic assume that all integer objects
           SRC1_PTR, mp_size_t SRC1_SIZE, mp_limb_t * SRC2_PTR,  are initialized.  You do that by calling the function `mpz_init'.  For
           mp_size_t SRC2_SIZE)  example,
      Puts at DEST_PTR the greatest common divisor of {SRC1_PTR,  
      SRC1_SIZE} and {SRC2_PTR, SRC2_SIZE}; both source operands are  
      destroyed by the operation.  The size in limbs of the greatest  
      common divisor is returned.  
   
      {SRC1_PTR, SRC1_SIZE} must be odd, and {SRC2_PTR, SRC2_SIZE} must       {
      have at least as many bits as {SRC1_PTR, SRC1_SIZE}.         mpz_t integ;
          mpz_init (integ);
          ...
          mpz_add (integ, ...);
          ...
          mpz_sub (integ, ...);
   
          /* Unless the program is about to exit, do ... */
          mpz_clear (integ);
        }
   
      *This interface is preliminary.  It might change incompatibly in     As you can see, you can store new values any number of times, once an
      future revisions.*  object is initialized.
   
  - Function: mp_limb_t mpn_gcd_1 (const mp_limb_t * SRC1_PTR, mp_size_t   - Function: void mpz_init (mpz_t INTEGER)
           SRC1_SIZE, mp_limb_t SRC2_LIMB)       Initialize INTEGER, and set its value to 0.
      Return the greatest common divisor of {SRC1_PTR, SRC1_SIZE} and  
      SRC2_LIMB, where SRC2_LIMB (as well as SRC1_SIZE) must be  
      different from 0.  
   
  - Function: mp_size_t mpn_gcdext (mp_limb_t * R1P, mp_limb_t * R2P,   - Function: void mpz_init2 (mpz_t INTEGER, unsigned long N)
           mp_limb_t * S1P, mp_size_t S1SIZE, mp_limb_t * S2P, mp_size_t       Initialize INTEGER, with space for N bits, and set its value to 0.
           S2SIZE)  
      Puts at R1P the greatest common divisor of {S1P, S1SIZE} and {S2P,  
      S2SIZE}.  The first cofactor is written at R2P.  Both source  
      operands are destroyed by the operation.  The size in limbs of the  
      greatest common divisor is returned.  
   
      *This interface is preliminary.  It might change incompatibly in       N is only the initial space, INTEGER will grow automatically in
      future revisions.*       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: mp_size_t mpn_sqrtrem (mp_limb_t * R1P, mp_limb_t * R2P,   - Function: void mpz_clear (mpz_t INTEGER)
           const mp_limb_t * SP, mp_size_t SIZE)       Free the space occupied by INTEGER.  Call this function for all
      Compute the square root of {SP, SIZE} and put the result at R1P.       `mpz_t' variables when you are done with them.
      Write the remainder at R2P, unless R2P is NULL.  
   
      Return the size of the remainder, whether R2P was NULL or non-NULL.   - Function: void mpz_realloc2 (mpz_t INTEGER, unsigned long N)
      Iff the operand was a perfect square, the return value will be 0.       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.
   
      The areas at R1P and SP have to be distinct.  The areas at R2P and       This function can be used to increase the space for a variable in
      SP have to be identical or completely separate, not partially       order to avoid repeated automatic reallocations, or to decrease it
      overlapping.       to give memory back to the heap.
   
      The area at R1P needs to have space for ceil(SIZE/2) limbs.  The   - Function: void mpz_array_init (mpz_t INTEGER_ARRAY[], size_t
      area at R2P needs to be SIZE limbs large.            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.
   
      *This interface is preliminary.  It might change incompatibly in       The space will not be automatically increased, unlike the normal
      future revisions.*       `mpz_init', but instead an application must ensure it's sufficient
        for any value stored.  The following space requirements apply to
        various functions,
   
  - Function: mp_size_t mpn_get_str (unsigned char *STR, int BASE,          * `mpz_abs', `mpz_neg', `mpz_set', `mpz_set_si' and
           mp_limb_t * S1P, mp_size_t S1SIZE)            `mpz_set_ui' need room for the value they store.
      Convert {S1P, S1SIZE} to a raw unsigned char array in base BASE.  
      The string is not in ASCII; to convert it to printable format, add  
      the ASCII codes for `0' or `A', depending on the base and range.  
      There may be leading zeros in the string.  
   
      The area at S1P is clobbered.          * `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'.
   
      Return the number of characters in STR.          * `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'.
   
      The area at STR has to have space for the largest possible number          * `mpz_swap' can be used between two array variables, but not
      represented by a S1SIZE long limb array, plus one extra character.            between an array and a normal variable.
   
  - Function: mp_size_t mpn_set_str (mp_limb_t * R1P, const char *STR,       For other functions, or if in doubt, the suggestion is to
           size_t strsize, int BASE)       calculate in a regular `mpz_init' variable and copy the result to
      Convert the raw unsigned char array at STR of length STRSIZE to a       an array variable with `mpz_set'.
      limb array {S1P, S1SIZE}.  The base of STR is BASE.  
   
      Return the number of limbs stored in R1P.       `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: unsigned long int mpn_scan0 (const mp_limb_t * S1P,   - Function: void * _mpz_realloc (mpz_t INTEGER, mp_size_t NEW_ALLOC)
           unsigned long int BIT)       Change the space for INTEGER to NEW_ALLOC limbs.  The value in
      Scan S1P from bit position BIT for the next clear bit.       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.
   
      It is required that there be a clear bit within the area at S1P at       `mpz_realloc2' is the preferred way to accomplish allocation
      or beyond bit position BIT, so that the function has something to       changes like this.  `mpz_realloc2' and `_mpz_realloc' are the same
      return.       except that `_mpz_realloc' takes the new size in limbs.
   
      *This interface is preliminary.  It might change incompatibly in  
      future revisions.*  File: gmp.info,  Node: Assigning Integers,  Next: Simultaneous Integer Init & Assign,  Prev: Initializing Integers,  Up: Integer Functions
   
  - Function: unsigned long int mpn_scan1 (const mp_limb_t * S1P,  Assignment Functions
           unsigned long int BIT)  ====================
      Scan S1P from bit position BIT for the next set bit.  
   
      It is required that there be a set bit within the area at S1P at or     These functions assign new values to already initialized integers
      beyond bit position BIT, so that the function has something to  (*note Initializing Integers::).
      return.  
   
      *This interface is preliminary.  It might change incompatibly in   - Function: void mpz_set (mpz_t ROP, mpz_t OP)
      future revisions.*   - Function: void mpz_set_ui (mpz_t ROP, unsigned long int OP)
    - Function: void mpz_set_si (mpz_t ROP, signed long int OP)
    - Function: void mpz_set_d (mpz_t ROP, double OP)
    - Function: void mpz_set_q (mpz_t ROP, mpq_t OP)
    - Function: void mpz_set_f (mpz_t ROP, mpf_t OP)
        Set the value of ROP from OP.
   
  - Function: void mpn_random2 (mp_limb_t * R1P, mp_size_t R1SIZE)       `mpz_set_d', `mpz_set_q' and `mpz_set_f' truncate OP to make it an
      Generate a random number of length R1SIZE with long strings of       integer.
      zeros and ones in the binary representation, and store it at R1P.  
   
      The generated random numbers are intended for testing the   - Function: int mpz_set_str (mpz_t ROP, char *STR, int BASE)
      correctness of the implementation of the `mpn' routines.       Set the value of ROP from STR, a null-terminated C string in base
        BASE.  White space is allowed in the string, and is simply
        ignored.  The base may vary from 2 to 36.  If BASE is 0, the
        actual base is determined from the leading characters: if the
        first two characters are "0x" or "0X", hexadecimal is assumed,
        otherwise if the first character is "0", octal is assumed,
        otherwise decimal is assumed.
   
  - Function: unsigned long int mpn_popcount (const mp_limb_t * S1P,       This function returns 0 if the entire string is a valid number in
           unsigned long int SIZE)       base BASE.  Otherwise it returns -1.
      Count the number of set bits in {S1P, SIZE}.  
   
  - Function: unsigned long int mpn_hamdist (const mp_limb_t * S1P,       [It turns out that it is not entirely true that this function
           const mp_limb_t * S2P, unsigned long int SIZE)       ignores white-space.  It does ignore it between digits, but not
      Compute the hamming distance between {S1P, SIZE} and {S2P, SIZE}.       after a minus sign or within or after "0x".  We are considering
        changing the definition of this function, making it fail when
        there is any white-space in the input, since that makes a lot of
        sense.  Send your opinion of this change to <bug-gmp@gnu.org>.  Do
        you really want it to accept "3 14" as meaning 314 as it does now?]
   
  - Function: int mpn_perfect_square_p (const mp_limb_t * S1P, mp_size_t   - Function: void mpz_swap (mpz_t ROP1, mpz_t ROP2)
           SIZE)       Swap the values ROP1 and ROP2 efficiently.
      Return non-zero iff {S1P, SIZE} is a perfect square.  
   
   
 File: gmp.info,  Node: BSD Compatible Functions,  Next: Custom Allocation,  Prev: Low-level Functions,  Up: Top  File: gmp.info,  Node: Simultaneous Integer Init & Assign,  Next: Converting Integers,  Prev: Assigning Integers,  Up: Integer Functions
   
 Berkeley MP Compatible Functions  Combined Initialization and Assignment Functions
 ********************************  ================================================
   
    These functions are intended to be fully compatible with the     For convenience, GMP provides a parallel series of
 Berkeley MP library which is available on many BSD derived U*ix systems.  initialize-and-set functions which initialize the output and then store
   the value there.  These functions' names have the form `mpz_init_set...'
   
    The original Berkeley MP library has a usage restriction: you cannot     Here is an example of using one:
 use the same variable as both source and destination in a single  
 function call.  The compatible functions in GNU MP do not share this  
 restriction--inputs and outputs may overlap.  
   
    It is not recommended that new programs are written using these       {
 functions.  Apart from the incomplete set of functions, the interface         mpz_t pie;
 for initializing `MINT' objects is more error prone, and the `pow'         mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10);
 function collides with `pow' in `libm.a'.         ...
          mpz_sub (pie, ...);
          ...
          mpz_clear (pie);
        }
   
    Include the header `mp.h' to get the definition of the necessary  Once the integer has been initialized by any of the `mpz_init_set...'
 types and functions.  If you are on a BSD derived system, make sure to  functions, it can be used as the source or destination operand for the
 include GNU `mp.h' if you are going to link the GNU `libmp.a' to you  ordinary integer functions.  Don't use an initialize-and-set function
 program.  This means that you probably need to give the -I<dir> option  on a variable already initialized!
 to the compiler, where <dir> is the directory where you have GNU `mp.h'.  
   
  - Function: MINT * itom (signed short int INITIAL_VALUE)   - Function: void mpz_init_set (mpz_t ROP, mpz_t OP)
      Allocate an integer consisting of a `MINT' object and dynamic limb   - Function: void mpz_init_set_ui (mpz_t ROP, unsigned long int OP)
      space.  Initialize the integer to INITIAL_VALUE.  Return a pointer   - Function: void mpz_init_set_si (mpz_t ROP, signed long int OP)
      to the `MINT' object.   - Function: void mpz_init_set_d (mpz_t ROP, double OP)
        Initialize ROP with limb space and set the initial numeric value
        from OP.
   
  - Function: MINT * xtom (char *INITIAL_VALUE)   - Function: int mpz_init_set_str (mpz_t ROP, char *STR, int BASE)
      Allocate an integer consisting of a `MINT' object and dynamic limb       Initialize ROP and set its value like `mpz_set_str' (see its
      space.  Initialize the integer from INITIAL_VALUE, a hexadecimal,       documentation above for details).
      '\0'-terminate C string.  Return a pointer to the `MINT' object.  
   
  - Function: void move (MINT *SRC, MINT *DEST)       If the string is a correct base BASE number, the function returns
      Set DEST to SRC by copying.  Both variables must be previously       0; if an error occurs it returns -1.  ROP is initialized even if
      initialized.       an error occurs.  (I.e., you have to call `mpz_clear' for it.)
   
  - Function: void madd (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION)  
      Add SRC_1 and SRC_2 and put the sum in DESTINATION.  File: gmp.info,  Node: Converting Integers,  Next: Integer Arithmetic,  Prev: Simultaneous Integer Init & Assign,  Up: Integer Functions
   
  - Function: void msub (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION)  Conversion Functions
      Subtract SRC_2 from SRC_1 and put the difference in DESTINATION.  ====================
   
  - Function: void mult (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION)     This section describes functions for converting GMP integers to
      Multiply SRC_1 and SRC_2 and put the product in DESTINATION.  standard C types.  Functions for converting _to_ GMP integers are
   described in *Note Assigning Integers:: and *Note I/O of Integers::.
   
  - Function: void mdiv (MINT *DIVIDEND, MINT *DIVISOR, MINT *QUOTIENT,   - Function: unsigned long int mpz_get_ui (mpz_t OP)
           MINT *REMAINDER)       Return the value of OP as an `unsigned long'.
  - Function: void sdiv (MINT *DIVIDEND, signed short int DIVISOR, MINT  
           *QUOTIENT, signed short int *REMAINDER)  
      Set QUOTIENT to DIVIDEND/DIVISOR, and REMAINDER to DIVIDEND mod  
      DIVISOR.  The quotient is rounded towards zero; the remainder has  
      the same sign as the dividend unless it is zero.  
   
      Some implementations of these functions work differently--or not       If OP is too big to fit an `unsigned long' then just the least
      at all--for negative arguments.       significant bits that do fit are returned.  The sign of OP is
        ignored, only the absolute value is used.
   
  - Function: void msqrt (MINT *OPERAND, MINT *ROOT, MINT *REMAINDER)   - Function: signed long int mpz_get_si (mpz_t OP)
      Set ROOT to the truncated integer part of the square root of       If OP fits into a `signed long int' return the value of OP.
      OPERAND.  Set REMAINDER to OPERAND-ROOT*ROOT, (i.e., zero if       Otherwise return the least significant part of OP, with the same
      OPERAND is a perfect square).       sign as OP.
   
      If ROOT and REMAINDER are the same variable, the results are       If OP is too big to fit in a `signed long int', the returned
      undefined.       result is probably not very useful.  To find out if the value will
        fit, use the function `mpz_fits_slong_p'.
   
  - Function: void pow (MINT *BASE, MINT *EXP, MINT *MOD, MINT *DEST)   - Function: double mpz_get_d (mpz_t OP)
      Set DEST to (BASE raised to EXP) modulo MOD.       Convert OP to a `double'.
   
  - Function: void rpow (MINT *BASE, signed short int EXP, MINT *DEST)   - Function: double mpz_get_d_2exp (signed long int *EXP, mpz_t OP)
      Set DEST to BASE raised to EXP.       Find D and EXP such that D times 2 raised to EXP, with
        0.5<=abs(D)<1, is a good approximation to OP.
   
  - Function: void gcd (MINT *OPERAND1, MINT *OPERAND2, MINT *RES)   - Function: char * mpz_get_str (char *STR, int BASE, mpz_t OP)
      Set RES to the greatest common divisor of OPERAND1 and OPERAND2.       Convert OP to a string of digits in base BASE.  The base may vary
        from 2 to 36.
   
  - Function: int mcmp (MINT *OPERAND1, MINT *OPERAND2)       If STR is `NULL', the result string is allocated using the current
      Compare OPERAND1 and OPERAND2.  Return a positive value if       allocation function (*note Custom Allocation::).  The block will be
      OPERAND1 > OPERAND2, zero if OPERAND1 = OPERAND2, and a negative       `strlen(str)+1' bytes, that being exactly enough for the string and
      value if OPERAND1 < OPERAND2.       null-terminator.
   
  - Function: void min (MINT *DEST)       If STR is not `NULL', it should point to a block of storage large
      Input a decimal string from `stdin', and put the read integer in       enough for the result, that being `mpz_sizeinbase (OP, BASE) + 2'.
      DEST.  SPC and TAB are allowed in the number string, and are       The two extra bytes are for a possible minus sign, and the
      ignored.       null-terminator.
   
  - Function: void mout (MINT *SRC)       A pointer to the result string is returned, being either the
      Output SRC to `stdout', as a decimal string.  Also output a       allocated block, or the given STR.
      newline.  
   
  - Function: char * mtox (MINT *OPERAND)   - Function: mp_limb_t mpz_getlimbn (mpz_t OP, mp_size_t N)
      Convert OPERAND to a hexadecimal string, and return a pointer to       Return limb number N from OP.  The sign of OP is ignored, just the
      the string.  The returned string is allocated using the default       absolute value is used.  The least significant limb is number 0.
      memory allocation function, `malloc' by default.  
   
  - Function: void mfree (MINT *OPERAND)       `mpz_size' can be used to find how many limbs make up OP.
      De-allocate, the space used by OPERAND.  *This function should       `mpz_getlimbn' returns zero if N is outside the range 0 to
      only be passed a value returned by `itom' or `xtom'.*       `mpz_size(OP)-1'.
   
   
 File: gmp.info,  Node: Custom Allocation,  Next: Contributors,  Prev: BSD Compatible Functions,  Up: Top  File: gmp.info,  Node: Integer Arithmetic,  Next: Integer Division,  Prev: Converting Integers,  Up: Integer Functions
   
 Custom Allocation  Arithmetic Functions
 *****************  ====================
   
    By default, the MP functions use `malloc', `realloc', and `free' for   - Function: void mpz_add (mpz_t ROP, mpz_t OP1, mpz_t OP2)
 memory allocation.  If `malloc' or `realloc' fails, the MP library   - Function: void mpz_add_ui (mpz_t ROP, mpz_t OP1, unsigned long int
 terminates execution after printing a fatal error message to standard            OP2)
 error.       Set ROP to OP1 + OP2.
   
    For some applications, you may wish to allocate memory in other   - Function: void mpz_sub (mpz_t ROP, mpz_t OP1, mpz_t OP2)
 ways, or you may not want to have a fatal error when there is no more   - Function: void mpz_sub_ui (mpz_t ROP, mpz_t OP1, unsigned long int
 memory available.  To accomplish this, you can specify alternative            OP2)
 memory allocation functions.   - Function: void mpz_ui_sub (mpz_t ROP, unsigned long int OP1, mpz_t
             OP2)
        Set ROP to OP1 - OP2.
   
  - Function: void mp_set_memory_functions (   - Function: void mpz_mul (mpz_t ROP, mpz_t OP1, mpz_t OP2)
           void *(*ALLOC_FUNC_PTR) (size_t),   - Function: void mpz_mul_si (mpz_t ROP, mpz_t OP1, long int OP2)
           void *(*REALLOC_FUNC_PTR) (void *, size_t, size_t),   - Function: void mpz_mul_ui (mpz_t ROP, mpz_t OP1, unsigned long int
           void (*FREE_FUNC_PTR) (void *, size_t))            OP2)
      Replace the current allocation functions from the arguments.  If       Set ROP to OP1 times OP2.
      an argument is NULL, the corresponding default function is  
      retained.  
   
      *Make sure to call this function in such a way that there are no   - Function: void mpz_addmul (mpz_t ROP, mpz_t OP1, mpz_t OP2)
      active MP objects that were allocated using the previously active   - Function: void mpz_addmul_ui (mpz_t ROP, mpz_t OP1, unsigned long
      allocation function!  Usually, that means that you have to call            int OP2)
      this function before any other MP function.*       Set ROP to ROP + OP1 times OP2.
   
    The functions you supply should fit the following declarations:   - Function: void mpz_submul (mpz_t ROP, mpz_t OP1, mpz_t OP2)
    - Function: void mpz_submul_ui (mpz_t ROP, mpz_t OP1, unsigned long
             int OP2)
        Set ROP to ROP - OP1 times OP2.
   
  - Function: void * allocate_function (size_t ALLOC_SIZE)   - Function: void mpz_mul_2exp (mpz_t ROP, mpz_t OP1, unsigned long int
      This function should return a pointer to newly allocated space            OP2)
      with at least ALLOC_SIZE storage units.       Set ROP to OP1 times 2 raised to OP2.  This operation can also be
        defined as a left shift by OP2 bits.
   
  - Function: void * reallocate_function (void *PTR, size_t OLD_SIZE,   - Function: void mpz_neg (mpz_t ROP, mpz_t OP)
           size_t NEW_SIZE)       Set ROP to -OP.
      This function should return a pointer to newly allocated space of  
      at least NEW_SIZE storage units, after copying at least the first  
      OLD_SIZE storage units from PTR.  It should also de-allocate the  
      space at PTR.  
   
      You can assume that the space at PTR was formerly returned from   - Function: void mpz_abs (mpz_t ROP, mpz_t OP)
      `allocate_function' or `reallocate_function', for a request for       Set ROP to the absolute value of OP.
      OLD_SIZE storage units.  
   
  - Function: void deallocate_function (void *PTR, size_t SIZE)  
      De-allocate the space pointed to by PTR.  File: gmp.info,  Node: Integer Division,  Next: Integer Exponentiation,  Prev: Integer Arithmetic,  Up: Integer Functions
   
      You can assume that the space at PTR was formerly returned from  Division Functions
      `allocate_function' or `reallocate_function', for a request for  ==================
      SIZE storage units.  
   
    (A "storage unit" is the unit in which the `sizeof' operator returns     Division is undefined if the divisor is zero.  Passing a zero
 the size of an object, normally an 8 bit byte.)  divisor to the division or modulo functions (including the modular
   powering functions `mpz_powm' and `mpz_powm_ui'), will cause an
   intentional division by zero.  This lets a program handle arithmetic
   exceptions in these functions the same way as for normal C `int'
   arithmetic.
   
    - Function: void mpz_cdiv_q (mpz_t Q, mpz_t N, mpz_t D)
 File: gmp.info,  Node: Contributors,  Next: References,  Prev: Custom Allocation,  Up: Top   - Function: void mpz_cdiv_r (mpz_t R, mpz_t N, mpz_t D)
    - Function: void mpz_cdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D)
    - Function: unsigned long int mpz_cdiv_q_ui (mpz_t Q, mpz_t N,
             unsigned long int D)
    - Function: unsigned long int mpz_cdiv_r_ui (mpz_t R, mpz_t N,
             unsigned long int D)
    - Function: unsigned long int mpz_cdiv_qr_ui (mpz_t Q, mpz_t R,
             mpz_t N, unsigned long int D)
    - Function: unsigned long int mpz_cdiv_ui (mpz_t N,
             unsigned long int D)
    - Function: void mpz_cdiv_q_2exp (mpz_t Q, mpz_t N,
             unsigned long int B)
    - Function: void mpz_cdiv_r_2exp (mpz_t R, mpz_t N,
             unsigned long int B)
   
 Contributors   - Function: void mpz_fdiv_q (mpz_t Q, mpz_t N, mpz_t D)
 ************   - Function: void mpz_fdiv_r (mpz_t R, mpz_t N, mpz_t D)
    - Function: void mpz_fdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D)
    - Function: unsigned long int mpz_fdiv_q_ui (mpz_t Q, mpz_t N,
             unsigned long int D)
    - Function: unsigned long int mpz_fdiv_r_ui (mpz_t R, mpz_t N,
             unsigned long int D)
    - Function: unsigned long int mpz_fdiv_qr_ui (mpz_t Q, mpz_t R,
             mpz_t N, unsigned long int D)
    - Function: unsigned long int mpz_fdiv_ui (mpz_t N,
             unsigned long int D)
    - Function: void mpz_fdiv_q_2exp (mpz_t Q, mpz_t N,
             unsigned long int B)
    - Function: void mpz_fdiv_r_2exp (mpz_t R, mpz_t N,
             unsigned long int B)
   
    I would like to thank Gunnar Sjoedin and Hans Riesel for their help   - Function: void mpz_tdiv_q (mpz_t Q, mpz_t N, mpz_t D)
 with mathematical problems, Richard Stallman for his help with design   - Function: void mpz_tdiv_r (mpz_t R, mpz_t N, mpz_t D)
 issues and for revising the first version of this manual, Brian Beuning   - Function: void mpz_tdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D)
 and Doug Lea for their testing of early versions of the library.   - Function: unsigned long int mpz_tdiv_q_ui (mpz_t Q, mpz_t N,
             unsigned long int D)
    - Function: unsigned long int mpz_tdiv_r_ui (mpz_t R, mpz_t N,
             unsigned long int D)
    - Function: unsigned long int mpz_tdiv_qr_ui (mpz_t Q, mpz_t R,
             mpz_t N, unsigned long int D)
    - Function: unsigned long int mpz_tdiv_ui (mpz_t N,
             unsigned long int D)
    - Function: void mpz_tdiv_q_2exp (mpz_t Q, mpz_t N,
             unsigned long int B)
    - Function: void mpz_tdiv_r_2exp (mpz_t R, mpz_t N,
             unsigned long int B)
   
    John Amanatides of York University in Canada contributed the function       Divide N by D, forming a quotient Q and/or remainder R.  For the
 `mpz_probab_prime_p'.       `2exp' functions, D=2^B.  The rounding is in three styles, each
        suiting different applications.
   
    Paul Zimmermann of Inria sparked the development of GMP 2, with his          * `cdiv' rounds Q up towards +infinity, and R will have the
 comparisons between bignum packages.            opposite sign to D.  The `c' stands for "ceil".
   
    Ken Weber (Kent State University, Universidade Federal do Rio Grande          * `fdiv' rounds Q down towards -infinity, and R will have the
 do Sul) contributed `mpz_gcd', `mpz_divexact', `mpn_gcd', and            same sign as D.  The `f' stands for "floor".
 `mpn_bdivmod', partially supported by CNPq (Brazil) grant 301314194-2.  
   
    Per Bothner of Cygnus Support helped to set up MP to use Cygnus'          * `tdiv' rounds Q towards zero, and R will have the same sign
 configure.  He has also made valuable suggestions and tested numerous            as N.  The `t' stands for "truncate".
 intermediary releases.  
   
    Joachim Hollman was involved in the design of the `mpf' interface,       In all cases Q and R will satisfy N=Q*D+R, and R will satisfy
 and in the `mpz' design revisions for version 2.       0<=abs(R)<abs(D).
   
    Bennet Yee contributed the functions `mpz_jacobi' and `mpz_legendre'.       The `q' functions calculate only the quotient, the `r' functions
        only the remainder, and the `qr' functions calculate both.  Note
        that for `qr' the same variable cannot be passed for both Q and R,
        or results will be unpredictable.
   
    Andreas Schwab contributed the files `mpn/m68k/lshift.S' and       For the `ui' variants the return value is the remainder, and in
 `mpn/m68k/rshift.S'.       fact returning the remainder is all the `div_ui' functions do.  For
        `tdiv' and `cdiv' the remainder can be negative, so for those the
        return value is the absolute value of the remainder.
   
    The development of floating point functions of GNU MP 2, were       The `2exp' functions are right shifts and bit masks, but of course
 supported in part by the ESPRIT-BRA (Basic Research Activities) 6846       rounding the same as the other functions.  For positive N both
 project POSSO (POlynomial System SOlving).       `mpz_fdiv_q_2exp' and `mpz_tdiv_q_2exp' are simple bitwise right
        shifts.  For negative N, `mpz_fdiv_q_2exp' is effectively an
        arithmetic right shift treating N as twos complement the same as
        the bitwise logical functions do, whereas `mpz_tdiv_q_2exp'
        effectively treats N as sign and magnitude.
   
    GNU MP 2 was finished and released by TMG Datakonsult,   - Function: void mpz_mod (mpz_t R, mpz_t N, mpz_t D)
 Sodermannagatan 5, 116 23 STOCKHOLM, SWEDEN, in cooperation with the   - Function: unsigned long int mpz_mod_ui (mpz_t R, mpz_t N,
 IDA Center for Computing Sciences, USA.            unsigned long int D)
        Set R to N `mod' D.  The sign of the divisor is ignored; the
        result is always non-negative.
   
        `mpz_mod_ui' is identical to `mpz_fdiv_r_ui' above, returning the
 File: gmp.info,  Node: References,  Prev: Contributors,  Up: Top       remainder as well as setting R.  See `mpz_fdiv_ui' above if only
        the return value is wanted.
   
 References   - Function: void mpz_divexact (mpz_t Q, mpz_t N, mpz_t D)
 **********   - Function: void mpz_divexact_ui (mpz_t Q, mpz_t N, unsigned long D)
        Set Q to N/D.  These functions produce correct results only when
        it is known in advance that D divides N.
   
    * Donald E. Knuth, "The Art of Computer Programming", vol 2,       These routines are much faster than the other division functions,
      "Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981.       and are the best choice when exact division is known to occur, for
        example reducing a rational to lowest terms.
   
    * John D. Lipson, "Elements of Algebra and Algebraic Computing", The   - Function: int mpz_divisible_p (mpz_t N, mpz_t D)
      Benjamin Cummings Publishing Company Inc, 1981.   - Function: int mpz_divisible_ui_p (mpz_t N, unsigned long int D)
    - Function: int mpz_divisible_2exp_p (mpz_t N, unsigned long int B)
        Return non-zero if N is exactly divisible by D, or in the case of
        `mpz_divisible_2exp_p' by 2^B.
   
    * Richard M. Stallman, "Using and Porting GCC", Free Software   - Function: int mpz_congruent_p (mpz_t N, mpz_t C, mpz_t D)
      Foundation, 1995.   - Function: int mpz_congruent_ui_p (mpz_t N, unsigned long int C,
             unsigned long int D)
    - Function: int mpz_congruent_2exp_p (mpz_t N, mpz_t C, unsigned long
             int B)
        Return non-zero if N is congruent to C modulo D, or in the case of
        `mpz_congruent_2exp_p' modulo 2^B.
   
    * Peter L. Montgomery, "Modular Multiplication Without Trial  
      Division", in Mathematics of Computation, volume 44, number 170,  File: gmp.info,  Node: Integer Exponentiation,  Next: Integer Roots,  Prev: Integer Division,  Up: Integer Functions
      April 1985.  
   
    * Torbjorn Granlund and Peter L. Montgomery, "Division by Invariant  Exponentiation Functions
      Integers using Multiplication", in Proceedings of the SIGPLAN  ========================
      PLDI'94 Conference, June 1994.  
   
    * Tudor Jebelean, "An algorithm for exact division", Journal of   - Function: void mpz_powm (mpz_t ROP, mpz_t BASE, mpz_t EXP, mpz_t MOD)
      Symbolic Computation, v. 15, 1993, pp. 169-180.   - Function: void mpz_powm_ui (mpz_t ROP, mpz_t BASE, unsigned long int
             EXP, mpz_t MOD)
        Set ROP to (BASE raised to EXP) modulo MOD.
   
    * Kenneth Weber, "The accelerated integer GCD algorithm", ACM       Negative EXP is supported if an inverse BASE^-1 mod MOD exists
      Transactions on Mathematical Software, v. 21 (March), 1995, pp.       (see `mpz_invert' in *Note Number Theoretic Functions::).  If an
      111-122.       inverse doesn't exist then a divide by zero is raised.
   
    - Function: void mpz_pow_ui (mpz_t ROP, mpz_t BASE, unsigned long int
             EXP)
    - Function: void mpz_ui_pow_ui (mpz_t ROP, unsigned long int BASE,
             unsigned long int EXP)
        Set ROP to BASE raised to EXP.  The case 0^0 yields 1.
   
   
 File: gmp.info,  Node: Concept Index,  Up: Top  File: gmp.info,  Node: Integer Roots,  Next: Number Theoretic Functions,  Prev: Integer Exponentiation,  Up: Integer Functions
   
 Concept Index  Root Extraction Functions
 *************  =========================
   
 * Menu:   - Function: int mpz_root (mpz_t ROP, mpz_t OP, unsigned long int N)
        Set ROP to  the truncated integer part of the Nth root of OP.
        Return non-zero if the computation was exact, i.e., if OP is ROP
        to the Nth power.
   
 * gmp.h:                                MP Basics.   - Function: void mpz_sqrt (mpz_t ROP, mpz_t OP)
 * mp.h:                                 BSD Compatible Functions.       Set ROP to  the truncated integer part of the square root of OP.
 * Arithmetic functions <1>:             Float Arithmetic.  
 * Arithmetic functions:                 Integer Arithmetic.   - Function: void mpz_sqrtrem (mpz_t ROP1, mpz_t ROP2, mpz_t OP)
 * Bit manipulation functions:           Integer Logic and Bit Fiddling.       Set ROP1 to the truncated integer part of the square root of OP,
 * BSD MP compatible functions:          BSD Compatible Functions.       like `mpz_sqrt'.  Set ROP2 to the remainder OP-ROP1*ROP1, which
 * Comparison functions:                 Float Comparison.       will be zero if OP is a perfect square.
 * Conditions for copying GNU MP:        Copying.  
 * Conversion functions <1>:             Converting Integers.       If ROP1 and ROP2 are the same variable, the results are undefined.
 * Conversion functions:                 Converting Floats.  
 * Copying conditions:                   Copying.   - Function: int mpz_perfect_power_p (mpz_t OP)
 * Float arithmetic functions:           Float Arithmetic.       Return non-zero if OP is a perfect power, i.e., if there exist
 * Float assignment functions:           Assigning Floats.       integers A and B, with B>1, such that OP equals A raised to the
 * Float comparisons functions:          Float Comparison.       power B.
 * Float functions:                      Floating-point Functions.  
 * Float input and output functions:     I/O of Floats.       Under this definition both 0 and 1 are considered to be perfect
 * Floating-point functions:             Floating-point Functions.       powers.  Negative values of OP are accepted, but of course can
 * Floating-point number:                MP Basics.       only be odd perfect powers.
 * I/O functions <1>:                    I/O of Floats.  
 * I/O functions:                        I/O of Integers.   - Function: int mpz_perfect_square_p (mpz_t OP)
 * Initialization and assignment functions <1>: Simultaneous Float Init & Assign.       Return non-zero if OP is a perfect square, i.e., if the square
 * Initialization and assignment functions: Simultaneous Integer Init & Assign.       root of OP is an integer.  Under this definition both 0 and 1 are
 * Input functions <1>:                  I/O of Integers.       considered to be perfect squares.
 * Input functions:                      I/O of Floats.  
 * Installation:                         Installing MP.  
 * Integer:                              MP Basics.  
 * Integer arithmetic functions:         Integer Arithmetic.  
 * Integer assignment functions:         Assigning Integers.  
 * Integer conversion functions:         Converting Integers.  
 * Integer functions:                    Integer Functions.  
 * Integer input and output functions:   I/O of Integers.  
 * Limb:                                 MP Basics.  
 * Logical functions:                    Integer Logic and Bit Fiddling.  
 * Low-level functions:                  Low-level Functions.  
 * Miscellaneous float functions:        Miscellaneous Float Functions.  
 * Miscellaneous integer functions:      Miscellaneous Integer Functions.  
 * Output functions <1>:                 I/O of Floats.  
 * Output functions:                     I/O of Integers.  
 * Rational number:                      MP Basics.  
 * Rational number functions:            Rational Number Functions.  
 * Reporting bugs:                       Reporting Bugs.  
 * User-defined precision:               Floating-point Functions.  
   
Legend:
Removed from v.1.1.1.1  
changed lines
  Added in v.1.1.1.4
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>