=================================================================== RCS file: /home/cvs/OpenXM_contrib/gmp/Attic/gmp.info-2,v retrieving revision 1.1.1.3 retrieving revision 1.1.1.4 diff -u -p -r1.1.1.3 -r1.1.1.4 --- OpenXM_contrib/gmp/Attic/gmp.info-2 2000/12/01 05:44:46 1.1.1.3 +++ OpenXM_contrib/gmp/Attic/gmp.info-2 2003/08/25 16:06:02 1.1.1.4 @@ -1,1182 +1,1212 @@ -This is gmp.info, produced by makeinfo version 4.0 from gmp.texi. +This is gmp.info, produced by makeinfo version 4.2 from 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 * gmp: (gmp). GNU Multiple Precision Arithmetic Library. END-INFO-DIR-ENTRY - This file documents GNU MP, a library for arbitrary-precision -arithmetic. - - Copyright (C) 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 -Free Software Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Foundation. -  -File: gmp.info, Node: Integer Division, Next: Integer Exponentiation, Prev: Integer Arithmetic, Up: Integer Functions +File: gmp.info, Node: Parameter Conventions, Next: Memory Management, Prev: Variable Conventions, Up: GMP Basics -Division Functions -================== +Parameter Conventions +===================== - Division is undefined if the divisor is zero, and passing a zero -divisor to the divide or modulo functions, as well passing a zero mod -argument to the `mpz_powm' and `mpz_powm_ui' functions, will make these -functions intentionally divide by zero. This lets the user handle -arithmetic exceptions in these functions in the same manner as other -arithmetic exceptions. + When a GMP variable is used as a function parameter, it's +effectively a call-by-reference, meaning if the function stores a value +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. - There are three main groups of division functions: - * Functions that truncate the quotient towards 0. The names of - these functions start with `mpz_tdiv'. The `t' in the name is - short for `truncate'. + When a function is going to return a GMP result, it should designate +a parameter that it sets, like the library functions do. More than one +value can be returned by having more than one output parameter, again +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. - * Functions that round the quotient towards -infinity). The names - of these routines start with `mpz_fdiv'. The `f' in the name is - short for `floor'. + Here's an example accepting an `mpz_t' parameter, doing a +calculation, and storing the result to the indicated parameter. - * Functions that round the quotient towards +infinity. The names of - these routines start with `mpz_cdiv'. The `c' in the name is - short for `ceil'. + 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; + } - For each rounding mode, there are a couple of variants. Here `q' -means that the quotient is computed, while `r' means that the remainder -is computed. Functions that compute both the quotient and remainder -have `qr' in the name. + `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. - - Function: void mpz_tdiv_q (mpz_t Q, mpz_t N, mpz_t D) - - Function: unsigned long int mpz_tdiv_q_ui (mpz_t Q, mpz_t N, - unsigned long int D) - Set Q to [N/D], truncated towards 0. + 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. - The function `mpz_tdiv_q_ui' returns the absolute value of the true - remainder. + +File: gmp.info, Node: Memory Management, Next: Reentrancy, Prev: Parameter Conventions, Up: GMP Basics - - Function: void mpz_tdiv_r (mpz_t R, mpz_t N, mpz_t D) - - Function: unsigned long int mpz_tdiv_r_ui (mpz_t R, mpz_t N, - unsigned long int D) - Set R to (N - [N/D] * D), where the quotient is truncated towards - 0. Unless R becomes zero, it will get the same sign as N. +Memory Management +================= - The function `mpz_tdiv_r_ui' returns the absolute value of the - remainder. + The GMP types like `mpz_t' are small, containing only a couple of +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. - - Function: void mpz_tdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D) - - Function: unsigned long int mpz_tdiv_qr_ui (mpz_t Q, mpz_t R, mpz_t - N, unsigned long int D) - Set Q to [N/D], truncated towards 0. Set R to (N - [N/D] * D). - Unless R becomes zero, it will get the same sign as N. If Q and R - are the same variable, the results are undefined. + `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 function `mpz_tdiv_qr_ui' returns the absolute value of the - remainder. + `mpf_t' variables, in the current implementation, use a fixed amount +of space, determined by the chosen precision and allocated at +initialization, so their size doesn't change. - - Function: unsigned long int mpz_tdiv_ui (mpz_t N, unsigned long int - D) - Like `mpz_tdiv_r_ui', but the remainder is not stored anywhere; its - absolute value is just returned. + All memory is allocated using `malloc' and friends by default, but +this can be changed, see *Note Custom Allocation::. Temporary memory +on the stack is also used (via `alloca'), but this can be changed at +build-time if desired, see *Note Build Options::. - - Function: void mpz_fdiv_q (mpz_t Q, mpz_t N, mpz_t D) - - Function: unsigned long int mpz_fdiv_q_ui (mpz_t Q, mpz_t N, - unsigned long int D) - Set Q to N/D, rounded towards -infinity. + +File: gmp.info, Node: Reentrancy, Next: Useful Macros and Constants, Prev: Memory Management, Up: GMP Basics - The function `mpz_fdiv_q_ui' returns the remainder. +Reentrancy +========== - - Function: void mpz_fdiv_r (mpz_t R, mpz_t N, mpz_t D) - - Function: unsigned long int mpz_fdiv_r_ui (mpz_t R, mpz_t N, - unsigned long int D) - Set R to (N - N/D * D), where the quotient is rounded towards - -infinity. Unless R becomes zero, it will get the same sign as D. + GMP is reentrant and thread-safe, with some exceptions: - The function `mpz_fdiv_r_ui' returns the remainder. + * If configured with `--enable-alloca=malloc-notreentrant' (or with + `--enable-alloca=notreentrant' when `alloca' is not available), + then naturally GMP is not reentrant. - - Function: void mpz_fdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D) - - Function: unsigned long int mpz_fdiv_qr_ui (mpz_t Q, mpz_t R, mpz_t - N, unsigned long int D) - Set Q to N/D, rounded towards -infinity. Set R to (N - N/D * D). - Unless R becomes zero, it will get the same sign as D. If Q and R - are the same variable, the results are undefined. + * `mpf_set_default_prec' and `mpf_init' use a global variable for the + selected precision. `mpf_init2' can be used instead. - The function `mpz_fdiv_qr_ui' returns the remainder. + * `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: unsigned long int mpz_fdiv_ui (mpz_t N, unsigned long int - D) - Like `mpz_fdiv_r_ui', but the remainder is not stored anywhere; it - is just returned. + * `mp_set_memory_functions' uses global variables to store the + selected memory allocation functions. - - Function: void mpz_cdiv_q (mpz_t Q, mpz_t N, mpz_t D) - - Function: unsigned long int mpz_cdiv_q_ui (mpz_t Q, mpz_t N, - unsigned long int D) - Set Q to N/D, rounded towards +infinity. + * If the memory allocation functions set by a call to + `mp_set_memory_functions' (or `malloc' and friends by default) are + not reentrant, then GMP will not be reentrant either. - The function `mpz_cdiv_q_ui' returns the negated remainder. + * If the standard I/O functions such as `fwrite' are not reentrant + then the GMP I/O functions using them will not be reentrant either. - - Function: void mpz_cdiv_r (mpz_t R, mpz_t N, mpz_t D) - - Function: unsigned long int mpz_cdiv_r_ui (mpz_t R, mpz_t N, - unsigned long int D) - Set R to (N - N/D * D), where the quotient is rounded towards - +infinity. Unless R becomes zero, it will get the opposite sign - as D. + * It's safe for two threads to read from the same GMP variable + simultaneously, but it's not safe for one to read while the + another might be writing, nor for two threads to write + 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. - The function `mpz_cdiv_r_ui' returns the negated remainder. + * On SCO systems the default `' macros use per-file static + variables and may not be reentrant, depending whether the compiler + optimizes away fetches from them. The GMP text-based input + functions are affected. - - Function: void mpz_cdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D) - - Function: unsigned long int mpz_cdiv_qr_ui (mpz_t Q, mpz_t R, mpz_t - N, unsigned long int D) - Set Q to N/D, rounded towards +infinity. Set R to (N - N/D * D). - Unless R becomes zero, it will get the opposite sign as D. If Q - and R are the same variable, the results are undefined. - - The function `mpz_cdiv_qr_ui' returns the negated remainder. - - - Function: unsigned long int mpz_cdiv_ui (mpz_t N, unsigned long int - D) - Like `mpz_tdiv_r_ui', but the remainder is not stored anywhere; its - negated value is just returned. - - - Function: void mpz_mod (mpz_t R, mpz_t N, mpz_t D) - - Function: unsigned long int mpz_mod_ui (mpz_t R, mpz_t N, unsigned - long int D) - Set R to N `mod' D. The sign of the divisor is ignored; the - result is always non-negative. - - The function `mpz_mod_ui' returns the remainder. - - - Function: void mpz_divexact (mpz_t Q, mpz_t N, mpz_t D) - Set Q to N/D. This function produces correct results only when it - is known in advance that D divides N. - - Since mpz_divexact is much faster than any of the other routines - that produce the quotient (*note References:: Jebelean), it is the - best choice for instances in which exact division is known to - occur, such as reducing a rational to lowest terms. - - - Function: void mpz_tdiv_q_2exp (mpz_t Q, mpz_t N, unsigned long int - D) - Set Q to N divided by 2 raised to D. The quotient is truncated - towards 0. - - - Function: void mpz_tdiv_r_2exp (mpz_t R, mpz_t N, unsigned long int - D) - Divide N by (2 raised to D), rounding the quotient towards 0, and - put the remainder in R. Unless it is zero, R will have the same - sign as N. - - - Function: void mpz_fdiv_q_2exp (mpz_t Q, mpz_t N, unsigned long int - D) - Set Q to N divided by 2 raised to D, rounded towards -infinity. - This operation can also be defined as arithmetic right shift D bit - positions. - - - Function: void mpz_fdiv_r_2exp (mpz_t R, mpz_t N, unsigned long int - D) - Divide N by (2 raised to D), rounding the quotient towards - -infinity, and put the remainder in R. The sign of R will always - be positive. This operation can also be defined as masking of the - D least significant bits. -  -File: gmp.info, Node: Integer Exponentiation, Next: Integer Roots, Prev: Integer Division, Up: Integer Functions +File: gmp.info, Node: Useful Macros and Constants, Next: Compatibility with older versions, Prev: Reentrancy, Up: GMP Basics -Exponentiation Functions -======================== +Useful Macros and Constants +=========================== - - Function: void mpz_powm (mpz_t ROP, mpz_t BASE, mpz_t EXP, mpz_t MOD) - - 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) `mod' MOD. If EXP is negative, - the result is undefined. + - Global Constant: const int mp_bits_per_limb + The number of bits per limb. + - Macro: __GNU_MP_VERSION + - 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 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 of 0^0 yields 1. + - Global Constant: const char * const gmp_version + The GMP version number, as a null-terminated string, in the form + "i.j" or "i.j.k". This release is "4.1.2".  -File: gmp.info, Node: Integer Roots, Next: Number Theoretic Functions, Prev: Integer Exponentiation, Up: Integer Functions +File: gmp.info, Node: Compatibility with older versions, Next: Demonstration Programs, Prev: Useful Macros and Constants, Up: GMP Basics -Root Extraction Functions -========================= +Compatibility with older versions +================================= - - 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. + This version of GMP is upwardly binary compatible with all 4.x and +3.x versions, and upwardly compatible at the source level with all 2.x +versions, with the following exceptions. - - Function: void mpz_sqrt (mpz_t ROP, mpz_t OP) - Set ROP to the truncated integer part of the square root of OP. + * `mpn_gcd' had its source arguments swapped as of GMP 3.0, for + consistency with other `mpn' functions. - - Function: void mpz_sqrtrem (mpz_t ROP1, mpz_t ROP2, mpz_t OP) - Set ROP1 to the truncated integer part of the square root of OP, - like `mpz_sqrt'. Set ROP2 to OP-ROP1*ROP1, (i.e., zero if OP is a - perfect square). + * `mpf_get_prec' counted precision slightly differently in GMP 3.0 + and 3.0.1, but in 3.1 reverted to the 2.x style. - If ROP1 and ROP2 are the same variable, the results are undefined. + There are a number of compatibility issues between GMP 1 and GMP 2 +that of course also apply when porting applications from GMP 1 to GMP +4. Please see the GMP 2 manual for details. - - Function: int mpz_perfect_power_p (mpz_t OP) - Return non-zero if OP is a perfect power, i.e., if there exist - integers A and B, with B > 1, such that OP equals a raised to b. - Return zero otherwise. + The Berkeley MP compatibility library (*note BSD Compatible +Functions::) is source and binary compatible with the standard `libmp'. - - Function: int mpz_perfect_square_p (mpz_t OP) - Return non-zero if OP is a perfect square, i.e., if the square - root of OP is an integer. Return zero otherwise. -  -File: gmp.info, Node: Number Theoretic Functions, Next: Integer Comparisons, Prev: Integer Roots, Up: Integer Functions +File: gmp.info, Node: Demonstration Programs, Next: Efficiency, Prev: Compatibility with older versions, Up: GMP Basics -Number Theoretic Functions -========================== +Demonstration programs +====================== - - Function: int mpz_probab_prime_p (mpz_t N, int REPS) - If this function returns 0, N is definitely not prime. If it - returns 1, then N is `probably' prime. If it returns 2, then N is - surely prime. Reasonable values of reps vary from 5 to 10; a - higher value lowers the probability for a non-prime to pass as a - `probable' prime. + The `demos' subdirectory has some sample programs using GMP. These +aren't built or installed, but there's a `Makefile' with rules for them. +For instance, - The function uses Miller-Rabin's probabilistic test. + make pexpr + ./pexpr 68^975+10 - - Function: int mpz_nextprime (mpz_t ROP, mpz_t OP) - Set ROP to the next prime greater than OP. +The following programs are provided - This function uses a probabilistic algorithm to identify primes, - but for for practical purposes it's adequate, since the chance of - a composite passing will be extremely small. + * `pexpr' is an expression evaluator, the program used on the GMP + web page. - - Function: void mpz_gcd (mpz_t ROP, mpz_t OP1, mpz_t OP2) - Set ROP to the greatest common divisor of OP1 and OP2. The result - is always positive even if either of or both input operands are - negative. + * The `calc' subdirectory has a similar but simpler evaluator using + `lex' and `yacc'. - - Function: unsigned long int mpz_gcd_ui (mpz_t ROP, mpz_t OP1, - unsigned long int OP2) - Compute the greatest common divisor of OP1 and OP2. If ROP is not - `NULL', store the result there. + * The `expr' subdirectory is yet another expression evaluator, a + library designed for ease of use within a C program. See + `demos/expr/README' for more information. - If the result is small enough to fit in an `unsigned long int', it - is returned. If the result does not fit, 0 is returned, and the - result is equal to the argument OP1. Note that the result will - always fit if OP2 is non-zero. + * `factorize' is a Pollard-Rho factorization program. - - Function: void mpz_gcdext (mpz_t G, mpz_t S, mpz_t T, mpz_t A, mpz_t - B) - Compute G, S, and T, such that AS + BT = G = `gcd'(A, B). If T is - `NULL', that argument is not computed. + * `isprime' is a command-line interface to the `mpz_probab_prime_p' + function. - - Function: void mpz_lcm (mpz_t ROP, mpz_t OP1, mpz_t OP2) - Set ROP to the least common multiple of OP1 and OP2. + * `primes' counts or lists primes in an interval, using a sieve. - - Function: int mpz_invert (mpz_t ROP, mpz_t OP1, mpz_t OP2) - Compute the inverse of OP1 modulo OP2 and put the result in ROP. - Return non-zero if an inverse exists, zero otherwise. When the - function returns zero, ROP is undefined. + * `qcn' is an example use of `mpz_kronecker_ui' to estimate quadratic + class numbers. - - Function: int mpz_jacobi (mpz_t OP1, mpz_t OP2) - - Function: int mpz_legendre (mpz_t OP1, mpz_t OP2) - Compute the Jacobi and Legendre symbols, respectively. OP2 should - be odd and must be positive. + * 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'. - - Function: int mpz_si_kronecker (long A, mpz_t B); - - Function: int mpz_ui_kronecker (unsigned long A, mpz_t B); - - Function: int mpz_kronecker_si (mpz_t A, long B); - - Function: int mpz_kronecker_ui (mpz_t A, unsigned long B); - Calculate the value of the Kronecker/Jacobi symbol (A/B), with the - Kronecker extension (a/2)=(2/a) when a odd, or (a/2)=0 when a even. - All values of A and B give a well-defined result. See Henri - Cohen, section 1.4.2, for more information (*note References::). - See also the example program `demos/qcn.c' which uses - `mpz_kronecker_ui'. + +File: gmp.info, Node: Efficiency, Next: Debugging, Prev: Demonstration Programs, Up: GMP Basics - - Function: unsigned long int mpz_remove (mpz_t ROP, mpz_t OP, mpz_t F) - Remove all occurrences of the factor F from OP and store the - result in ROP. Return the multiplicity of F in OP. +Efficiency +========== - - Function: void mpz_fac_ui (mpz_t ROP, unsigned long int OP) - Set ROP to OP!, the factorial of OP. +Small operands + 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: void mpz_bin_ui (mpz_t ROP, mpz_t N, unsigned long int K) - - Function: void mpz_bin_uiui (mpz_t ROP, unsigned long int N, - unsigned long int K) - Compute the binomial coefficient N over K and store the result in - ROP. Negative values of N are supported by `mpz_bin_ui', using - the identity bin(-n,k) = (-1)^k * bin(n+k-1,k) (see Knuth volume 1 - section 1.2.6 part G). +Static Linking + On some CPUs, in particular the x86s, the static `libgmp.a' should + be used for maximum speed, since the PIC code in the shared + `libgmp.so' will have a small overhead on each function call and + global data address. For many programs this will be + insignificant, but for long calculations there's a gain to be had. - - Function: void mpz_fib_ui (mpz_t ROP, unsigned long int N) - Compute the Nth Fibonacci number and store the result in ROP. +Initializing and clearing + Avoid excessive initializing and clearing of variables, since this + can be quite time consuming, especially in comparison to otherwise + fast operations like addition. - -File: gmp.info, Node: Integer Comparisons, Next: Integer Logic and Bit Fiddling, Prev: Number Theoretic Functions, Up: Integer Functions + A language interpreter might want to keep a free list or stack of + initialized variables ready for use. It should be possible to + integrate something like that with a garbage collector too. -Comparison Functions -==================== +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::). - - Function: int mpz_cmp (mpz_t OP1, mpz_t OP2) - Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero - if OP1 = OP2, and a negative value if OP1 < OP2. + It doesn't matter if a size set with `mpz_init2' or `mpz_realloc2' + is too small, since all functions will do a further reallocation + if necessary. Badly overestimating memory required will waste + space though. - - Macro: int mpz_cmp_ui (mpz_t OP1, unsigned long int OP2) - - Macro: int mpz_cmp_si (mpz_t OP1, signed long int OP2) - Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero - if OP1 = OP2, and a negative value if OP1 < OP2. +`2exp' functions + It's up to an application to call functions like `mpz_mul_2exp' + when appropriate. General purpose functions like `mpz_mul' make + 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. - These functions are actually implemented as macros. They evaluate - their arguments multiple times. +`ui' and `si' 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. - - Function: int mpz_cmpabs (mpz_t OP1, mpz_t OP2) - - Function: int mpz_cmpabs_ui (mpz_t OP1, unsigned long int OP2) - Compare the absolute values of OP1 and OP2. Return a positive - value if OP1 > OP2, zero if OP1 = OP2, and a negative value if OP1 - < OP2. +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. - - Macro: int mpz_sgn (mpz_t OP) - Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0. + `mpz_add_ui', `mpz_sub_ui', `mpf_add_ui' and `mpf_sub_ui' benefit + from an in-place operation like `mpz_add_ui(x,x,y)', since usually + only one or two limbs of `x' will need to be changed. The same + 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. - This function is actually implemented as a macro. It evaluates its - arguments multiple times. + `mpz_mul' is currently the opposite, a separate destination is + slightly better. A call like `mpz_mul(x,x,y)' will, unless `y' is + only one limb, make a temporary copy of `x' before forming the + result. Normally that copying will only be a tiny fraction of the + time for the multiply, so this is not a particularly important + consideration. - -File: gmp.info, Node: Integer Logic and Bit Fiddling, Next: I/O of Integers, Prev: Integer Comparisons, Up: Integer Functions + `mpz_set', `mpq_set', `mpq_set_num', `mpf_set', etc, make no + attempt to recognise a copy of something to itself, so a call like + `mpz_set(x,x)' will be wasteful. Naturally that would never be + written deliberately, but if it might arise from two pointers to + the same object then a test to avoid it might be desirable. -Logical and Bit Manipulation Functions -====================================== + if (x != y) + mpz_set (x, y); - These functions behave as if two's complement arithmetic were used -(although sign-magnitude is used by the actual implementation). + Note that it's never worth introducing extra `mpz_set' calls just + to get in-place operations. If a result should go to a particular + variable then just direct it there and let GMP take care of data + movement. - - Function: void mpz_and (mpz_t ROP, mpz_t OP1, mpz_t OP2) - Set ROP to OP1 logical-and OP2. +Divisibility Testing (Small Integers) + `mpz_divisible_ui_p' and `mpz_congruent_ui_p' are the best + 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 mpz_ior (mpz_t ROP, mpz_t OP1, mpz_t OP2) - Set ROP to OP1 inclusive-or OP2. + However when testing divisibility by several small integers, it's + 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 mpz_xor (mpz_t ROP, mpz_t OP1, mpz_t OP2) - Set ROP to OP1 exclusive-or OP2. + The division functions like `mpz_tdiv_q_ui' which give a quotient + 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 mpz_com (mpz_t ROP, mpz_t OP) - Set ROP to the one's complement of OP. +Rational Arithmetic + The `mpq' functions operate on `mpq_t' values with no common + 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: unsigned long int mpz_popcount (mpz_t OP) - For non-negative numbers, return the population count of OP. For - negative numbers, return the largest possible value (MAX_ULONG). + However, applications that know something about the factorization + of the values they're working with might be able to avoid some of + 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. - - Function: unsigned long int mpz_hamdist (mpz_t OP1, mpz_t OP2) - If OP1 and OP2 are both non-negative, return the hamming distance - between the two operands. Otherwise, return the largest possible - value (MAX_ULONG). + 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::. - It is possible to extend this function to return a useful value - when the operands are both negative, but the current - implementation returns MAX_ULONG in this case. *Do not depend on - this behavior, since it will change in a future release.* + 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, - - Function: unsigned long int mpz_scan0 (mpz_t OP, unsigned long int - STARTING_BIT) - Scan OP, starting with bit STARTING_BIT, towards more significant - bits, until the first clear bit is found. Return the index of the - found bit. + /* 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); - - Function: unsigned long int mpz_scan1 (mpz_t OP, unsigned long int - STARTING_BIT) - Scan OP, starting with bit STARTING_BIT, towards more significant - bits, until the first set bit is found. Return the index of the - found bit. +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. - - Function: void mpz_setbit (mpz_t ROP, unsigned long int BIT_INDEX) - Set bit BIT_INDEX in ROP. +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. - - Function: void mpz_clrbit (mpz_t ROP, unsigned long int BIT_INDEX) - Clear bit BIT_INDEX in ROP. + 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. - - Function: int mpz_tstbit (mpz_t OP, unsigned long int BIT_INDEX) - Check bit BIT_INDEX in OP and return 0 or 1 accordingly. -  -File: gmp.info, Node: I/O of Integers, Next: Integer Random Numbers, Prev: Integer Logic and Bit Fiddling, Up: Integer Functions +File: gmp.info, Node: Debugging, Next: Profiling, Prev: Efficiency, Up: GMP Basics -Input and Output Functions -========================== +Debugging +========= - Functions that perform input from a stdio stream, and functions that -output to a stdio stream. Passing a `NULL' pointer for a STREAM -argument to any of these functions will make them read from `stdin' and -write to `stdout', respectively. +Stack Overflow + Depending on the system, a segmentation violation or bus error + might be the only indication of stack overflow. See + `--enable-alloca' choices in *Note Build Options::, for how to + address this. - When using any of these functions, it is a good idea to include -`stdio.h' before `gmp.h', since that will allow `gmp.h' to define -prototypes for these functions. + In new enough versions of GCC, `-fstack-check' may be able to + ensure an overflow is recognised by the system before too much + 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: size_t mpz_out_str (FILE *STREAM, int BASE, mpz_t OP) - Output OP on stdio stream STREAM, as a string of digits in base - BASE. The base may vary from 2 to 36. +Heap Problems + The most likely cause of application problems with GMP is heap + 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. - Return the number of bytes written, or if an error occurred, - return 0. + In all such cases a malloc debugger is recommended. On a GNU or + 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 - - Function: size_t mpz_inp_str (mpz_t ROP, FILE *STREAM, int BASE) - Input a possibly white-space preceded string in base BASE from - stdio stream STREAM, and put the read integer in ROP. 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. + `http://www.inf.ethz.ch/personal/biere/projects/ccmalloc' + `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' - Return the number of bytes read, or if an error occurred, return 0. + The GMP default allocation routines in `memory.c' also have a + 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. - - Function: size_t mpz_out_raw (FILE *STREAM, mpz_t OP) - Output OP on stdio stream STREAM, in raw binary format. The - integer is written in a portable format, with 4 bytes of size - information, and that many bytes of limbs. Both the size and the - limbs are written in decreasing significance order (i.e., in - big-endian). +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. - The output can be read with `mpz_inp_raw'. +GNU Debugger + A sample `.gdbinit' is included in the distribution, showing how + to call some undocumented dump functions to print GMP variables + 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. - Return the number of bytes written, or if an error occurred, - return 0. +Source File Paths + GMP has multiple source files with the same name, in different + 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. - The output of this can not be read by `mpz_inp_raw' from GMP 1, - because of changes necessary for compatibility between 32-bit and - 64-bit machines. + cd /my/build/dir + /my/source/dir/gmp-4.1.2/configure - - Function: size_t mpz_inp_raw (mpz_t ROP, FILE *STREAM) - Input from stdio stream STREAM in the format written by - `mpz_out_raw', and put the result in ROP. Return the number of - bytes read, or if an error occurred, return 0. + This works via `VPATH', and might require GNU `make'. Alternately + it might be possible to change the `.c.lo' rules appropriately. - This routine can read the output from `mpz_out_raw' also from GMP - 1, in spite of changes necessary for compatibility between 32-bit - and 64-bit machines. +Assertion Checking + 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. - -File: gmp.info, Node: Integer Random Numbers, Next: Miscellaneous Integer Functions, Prev: I/O of Integers, Up: Integer Functions + Applications using the low-level `mpn' functions, however, will + benefit from `--enable-assert' since it adds checks on the + parameters of most such functions, many of which have subtle + restrictions on their usage. Note however that only the generic C + code has checks, not the assembler code, so CPU `none' should be + used for maximum checking. -Random Number Functions -======================= +Temporary Memory Checking + The build option `--enable-alloca=debug' arranges that each block + of temporary memory in GMP is allocated with a separate call to + `malloc' (or the allocation function set with + `mp_set_memory_functions'). - The random number functions of GMP come in two groups; older function -that rely on a global state, and newer functions that accept a state -parameter that is read and modified. Please see the *Note Random -Number Functions:: for more information on how to use and not to use -random number functions. + This can help a malloc debugger detect accesses outside the + intended bounds, or detect memory not released. In a normal + 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. - - Function: void mpz_urandomb (mpz_t ROP, gmp_randstate_t STATE, - unsigned long int N) Generate a uniformly distributed random - integer in the range 0 to 2^N - 1, inclusive. +Maximum Debuggability + To summarize the above, a GMP build for maximum debuggability + would be - The variable STATE must be initialized by calling one of the - `gmp_randinit' functions (*Note Random State Initialization::) - before invoking this function. + ./configure --disable-shared --enable-assert \ + --enable-alloca=debug --host=none CFLAGS=-g - - Function: void mpz_urandomm (mpz_t ROP, gmp_randstate_t STATE, - mpz_t N) Generate a uniform random integer in the range 0 to N - - 1, inclusive. + For C++, add `--enable-cxx CXXFLAGS=-g'. - The variable STATE must be initialized by calling one of the - `gmp_randinit' functions (*Note Random State Initialization::) - before invoking this function. +Checker + The checker program (`http://savannah.gnu.org/projects/checker') + can be used with GMP. It contains a stub library which means GMP + applications compiled with checker can use a normal GMP build. - - Function: void mpz_rrandomb (mpz_t ROP, gmp_randstate_t STATE, - unsigned long int N) - Generate a random integer with long strings of zeros and ones in - the binary representation. Useful for testing functions and - algorithms, since this kind of random numbers have proven to be - more likely to trigger corner-case bugs. The random number will - be in the range 0 to 2^N - 1, inclusive. + A build of GMP with checking within GMP itself can be made. This + will run very very slowly. Configure with - The variable STATE must be initialized by calling one of the - `gmp_randinit' functions (*Note Random State Initialization::) - before invoking this function. + ./configure --host=none-pc-linux-gnu CC=checkergcc - - Function: void mpz_random (mpz_t ROP, mp_size_t MAX_SIZE) - Generate a random integer of at most MAX_SIZE limbs. The generated - random number doesn't satisfy any particular requirements of - randomness. Negative random numbers are generated when MAX_SIZE - is negative. + `--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. - This function is obsolete. Use `mpz_urandomb' or `mpz_urandomm' - instead. +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. - - Function: void mpz_random2 (mpz_t ROP, mp_size_t MAX_SIZE) - Generate a random integer of at most MAX_SIZE limbs, with long - strings of zeros and ones in the binary representation. 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. + 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::). - This function is obsolete. Use `mpz_rrandomb' instead. +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: Miscellaneous Integer Functions, Prev: Integer Random Numbers, Up: Integer Functions +File: gmp.info, Node: Profiling, Next: Autoconf, Prev: Debugging, Up: GMP Basics -Miscellaneous Functions -======================= +Profiling +========= - - Function: int mpz_fits_ulong_p (mpz_t OP) - - Function: int mpz_fits_slong_p (mpz_t OP) - - Function: int mpz_fits_uint_p (mpz_t OP) - - Function: int mpz_fits_sint_p (mpz_t OP) - - Function: int mpz_fits_ushort_p (mpz_t OP) - - Function: int mpz_fits_sshort_p (mpz_t OP) - Return non-zero iff the value of OP fits in an `unsigned long int', - `signed long int', `unsigned int', `signed int', `unsigned short - int', or `signed short int', respectively. Otherwise, return zero. + Running a program under a profiler is a good way to find where it's +spending most time and where improvements can be best sought. - - Macro: int mpz_odd_p (mpz_t OP) - - Macro: int mpz_even_p (mpz_t OP) - Determine whether OP is odd or even, respectively. Return - non-zero if yes, zero if no. These macros evaluate their - arguments more than once. + 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. - - Function: size_t mpz_size (mpz_t OP) - Return the size of OP measured in number of limbs. If OP is zero, - the returned value will be zero. + The `--enable-profiling' build option can be used to add suitable +compiler flags, either for `prof' (`-p') or `gprof' (`-pg'), see *Note +Build Options::. Which of the two is available and what they do will +depend on the system, and possibly on support available in `libc'. For +some systems appropriate corresponding `mcount' calls are added to the +assembler code too. - - Function: size_t mpz_sizeinbase (mpz_t OP, int BASE) - Return the size of OP measured in number of digits in base BASE. - The base may vary from 2 to 36. The returned value will be exact - or 1 too big. If BASE is a power of 2, the returned value will - always be exact. + On x86 systems `prof' gives call counting, so that average time spent +in a function can be determined. `gprof', where supported, adds call +graph construction, so for instance calls to `mpn_add_n' from `mpz_add' +and from `mpz_mul' can be differentiated. - This function is useful in order to allocate the right amount of - space before converting OP to a string. The right amount of - allocation is normally two more than the value returned by - `mpz_sizeinbase' (one extra for a minus sign and one for the - terminating '\0'). + On x86 and 68k systems `-pg' and `-fomit-frame-pointer' are +incompatible, so the latter is not used when `gprof' profiling is +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.  -File: gmp.info, Node: Rational Number Functions, Next: Floating-point Functions, Prev: Integer Functions, Up: Top +File: gmp.info, Node: Autoconf, Next: Emacs, Prev: Profiling, Up: GMP Basics -Rational Number Functions -************************* +Autoconf +======== - This chapter describes the GMP functions for performing arithmetic -on rational numbers. These functions start with the prefix `mpq_'. + Autoconf based applications can easily check whether GMP is +installed. The only thing to be noted is that GMP library symbols from +version 3 onwards have prefixes like `__gmpz'. The following therefore +would be a simple test, - Rational numbers are stored in objects of type `mpq_t'. + AC_CHECK_LIB(gmp, __gmpz_init) - All rational arithmetic functions assume operands have a canonical -form, and canonicalize their result. The canonical from means that the -denominator and the numerator have no common factors, and that the -denominator is positive. Zero has the unique representation 0/1. + This just uses the default `AC_CHECK_LIB' actions for found or not +found, but an application that must have GMP would want to generate an +error if not found. For example, - Pure assignment functions do not canonicalize the assigned variable. -It is the responsibility of the user to canonicalize the assigned -variable before any arithmetic operations are performed on that -variable. *Note that this is an incompatible change from version 1 of -the library.* + AC_CHECK_LIB(gmp, __gmpz_init, , [AC_MSG_ERROR( + [GNU MP not found, see http://swox.com/gmp])]) - - Function: void mpq_canonicalize (mpq_t OP) - Remove any factors that are common to the numerator and - denominator of OP, and make the denominator positive. + If functions added in some particular version of GMP are required, +then one of those can be used when checking. For example `mpz_mul_si' +was added in GMP 3.1, -* Menu: + AC_CHECK_LIB(gmp, __gmpz_mul_si, , [AC_MSG_ERROR( + [GNU MP not found, or not 3.1 or up, see http://swox.com/gmp])]) -* Initializing Rationals:: -* Rational Arithmetic:: -* Comparing Rationals:: -* Applying Integer Functions:: -* I/O of Rationals:: -* Miscellaneous Rational Functions:: + An alternative would be to test the version number in `gmp.h' using +say `AC_EGREP_CPP'. That would make it possible to test the exact +version, if some particular sub-minor release is known to be necessary. - -File: gmp.info, Node: Initializing Rationals, Next: Rational Arithmetic, Prev: Rational Number Functions, Up: Rational Number Functions + An application that can use either GMP 2 or 3 will need to test for +`__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, -Initialization and Assignment Functions -======================================= + AC_CHECK_LIB(gmp, __gmpz_init, , + [AC_CHECK_LIB(gmp, mpz_init, , + [AC_CHECK_LIB(gmp2, mpz_init)])]) - - Function: void mpq_init (mpq_t DEST_RATIONAL) - Initialize DEST_RATIONAL and set it to 0/1. Each variable should - normally only be initialized once, or at least cleared out (using - the function `mpq_clear') between each initialization. + In general it's suggested that applications should simply demand a +new enough GMP rather than trying to provide supplements for features +not available in past versions. - - Function: void mpq_clear (mpq_t RATIONAL_NUMBER) - Free the space occupied by RATIONAL_NUMBER. Make sure to call this - function for all `mpq_t' variables when you are done with them. + Occasionally an application will need or want to know the size of a +type at configuration or preprocessing time, not just with `sizeof' in +the code. This can be done in the normal way with `mp_limb_t' etc, but +GMP 4.0 or up is best for this, since prior versions needed certain +`-D' defines on systems using a `long long' limb. The following would +suit Autoconf 2.50 or up, - - Function: void mpq_set (mpq_t ROP, mpq_t OP) - - Function: void mpq_set_z (mpq_t ROP, mpz_t OP) - Assign ROP from OP. + AC_CHECK_SIZEOF(mp_limb_t, , [#include ]) - - Function: void mpq_set_ui (mpq_t ROP, unsigned long int OP1, - unsigned long int OP2) - - Function: void mpq_set_si (mpq_t ROP, signed long int OP1, unsigned - long int OP2) - Set the value of ROP to OP1/OP2. Note that if OP1 and OP2 have - common factors, ROP has to be passed to `mpq_canonicalize' before - any operations are performed on ROP. + The optional `mpfr' functions are provided in a separate +`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 mpq_swap (mpq_t ROP1, mpq_t ROP2) - Swap the values ROP1 and ROP2 efficiently. + AC_CHECK_LIB(mpfr, mpfr_add, , [AC_MSG_ERROR( + [Need MPFR either from GNU MP 4 or separate MPFR package. + See http://www.mpfr.org or http://swox.com/gmp])  -File: gmp.info, Node: Rational Arithmetic, Next: Comparing Rationals, Prev: Initializing Rationals, Up: Rational Number Functions +File: gmp.info, Node: Emacs, Prev: Autoconf, Up: GMP Basics -Arithmetic Functions -==================== +Emacs +===== - - Function: void mpq_add (mpq_t SUM, mpq_t ADDEND1, mpq_t ADDEND2) - Set SUM to ADDEND1 + ADDEND2. + (`info-lookup-symbol') is a good way to find documentation +on C functions while editing (*note Info Documentation Lookup: +(emacs)Info Lookup.). - - Function: void mpq_sub (mpq_t DIFFERENCE, mpq_t MINUEND, mpq_t - SUBTRAHEND) - Set DIFFERENCE to MINUEND - SUBTRAHEND. + The GMP manual can be included in such lookups by putting the +following in your `.emacs', - - Function: void mpq_mul (mpq_t PRODUCT, mpq_t MULTIPLIER, mpq_t - MULTIPLICAND) - Set PRODUCT to MULTIPLIER times MULTIPLICAND. + (eval-after-load "info-look" + '(let ((mode-value (assoc 'c-mode (assoc 'symbol info-lookup-alist)))) + (setcar (nthcdr 3 mode-value) + (cons '("(gmp)Function Index" nil "^ -.* " "\\>") + (nth 3 mode-value))))) - - Function: void mpq_div (mpq_t QUOTIENT, mpq_t DIVIDEND, mpq_t - DIVISOR) - Set QUOTIENT to DIVIDEND/DIVISOR. + The same can be done for MPFR, with `(mpfr)' in place of `(gmp)'. - - Function: void mpq_neg (mpq_t NEGATED_OPERAND, mpq_t OPERAND) - Set NEGATED_OPERAND to -OPERAND. - - - Function: void mpq_inv (mpq_t INVERTED_NUMBER, mpq_t NUMBER) - Set INVERTED_NUMBER to 1/NUMBER. If the new denominator is zero, - this routine will divide by zero. -  -File: gmp.info, Node: Comparing Rationals, Next: Applying Integer Functions, Prev: Rational Arithmetic, Up: Rational Number Functions +File: gmp.info, Node: Reporting Bugs, Next: Integer Functions, Prev: GMP Basics, Up: Top -Comparison Functions -==================== +Reporting Bugs +************** - - Function: int mpq_cmp (mpq_t OP1, mpq_t OP2) - Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero - if OP1 = OP2, and a negative value if OP1 < OP2. + If you think you have found a bug in the GMP library, please +investigate it and report it. We have made this library available to +you, and it is not too much to ask you to report the bugs you find. - To determine if two rationals are equal, `mpq_equal' is faster than - `mpq_cmp'. + Before you report a bug, check it's not already addressed in *Note +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. - - Macro: int mpq_cmp_ui (mpq_t OP1, unsigned long int NUM2, unsigned - long int DEN2) - Compare OP1 and NUM2/DEN2. Return a positive value if OP1 > - NUM2/DEN2, zero if OP1 = NUM2/DEN2, and a negative value if OP1 < - NUM2/DEN2. + Please include the following in any report, - This routine allows that NUM2 and DEN2 have common factors. + * The GMP version number, and if pre-packaged or patched then say so. - This function is actually implemented as a macro. It evaluates its - arguments multiple times. + * A test program that makes it possible for us to reproduce the bug. + Include instructions on how to run the program. - - Macro: int mpq_sgn (mpq_t OP) - Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0. + * A description of what is wrong. If the results are incorrect, in + what way. If you get a crash, say so. - This function is actually implemented as a macro. It evaluates its - arguments multiple times. + * If you get a crash, include a stack backtrace from the debugger if + it's informative (`where' in `gdb', or `$C' in `adb'). - - Function: int mpq_equal (mpq_t OP1, mpq_t OP2) - Return non-zero if OP1 and OP2 are equal, zero if they are - non-equal. Although `mpq_cmp' can be used for the same purpose, - this function is much faster. + * Please do not send core dumps, executables or `strace's. - -File: gmp.info, Node: Applying Integer Functions, Next: I/O of Rationals, Prev: Comparing Rationals, Up: Rational Number Functions + * The configuration options you used when building GMP, if any. -Applying Integer Functions to Rationals -======================================= + * The name of the compiler and its version. For `gcc', get the + version with `gcc -v', otherwise perhaps `what `which cc`', or + similar. - The set of `mpq' functions is quite small. In particular, there are -few functions for either input or output. But there are two macros -that allow us to apply any `mpz' function on the numerator or -denominator of a rational number. If these macros are used to assign -to the rational number, `mpq_canonicalize' normally need to be called -afterwards. + * The output from running `uname -a'. - - Macro: mpz_t mpq_numref (mpq_t OP) - - Macro: mpz_t mpq_denref (mpq_t OP) - Return a reference to the numerator and denominator of OP, - respectively. The `mpz' functions can be used on the result of - these macros. + * The output from running `./config.guess', and from running + `./configfsf.guess' (might be the same). - -File: gmp.info, Node: I/O of Rationals, Next: Miscellaneous Rational Functions, Prev: Applying Integer Functions, Up: Rational Number Functions + * If the bug is related to `configure', then the contents of + `config.log'. -Input and Output Functions -========================== + * If the bug is related to an `asm' file not assembling, then the + contents of `config.m4' and the offending line or lines from the + temporary `mpn/tmp-.s'. - Functions that perform input from a stdio stream, and functions that -output to a stdio stream. Passing a `NULL' pointer for a STREAM -argument to any of these functions will make them read from `stdin' and -write to `stdout', respectively. + Please make an effort to produce a self-contained report, with +something definite that can be tested or debugged. Vague queries or +piecemeal messages are difficult to act on and don't help the +development effort. - When using any of these functions, it is a good idea to include -`stdio.h' before `gmp.h', since that will allow `gmp.h' to define -prototypes for these functions. + It is not uncommon that an observed problem is actually due to a bug +in the compiler; the GMP code tends to explore interesting corners in +compilers. - - Function: size_t mpq_out_str (FILE *STREAM, int BASE, mpq_t OP) - Output OP on stdio stream STREAM, as a string of digits in base - BASE. The base may vary from 2 to 36. Output is in the form - `num/den' or if the denominator is 1 then just `num'. + If your bug report is good, we will do our best to help you get a +corrected version of the library; if the bug report is poor, we won't +do anything about it (except maybe ask you to send a better report). - Return the number of bytes written, or if an error occurred, - return 0. + Send your report to: . + If you think something in this manual is unclear, or downright +incorrect, or if the language needs to be improved, please send a note +to the same address. +  -File: gmp.info, Node: Miscellaneous Rational Functions, Prev: I/O of Rationals, Up: Rational Number Functions +File: gmp.info, Node: Integer Functions, Next: Rational Number Functions, Prev: Reporting Bugs, Up: Top -Miscellaneous Functions -======================= +Integer Functions +***************** - - Function: double mpq_get_d (mpq_t OP) - Convert OP to a double. + This chapter describes the GMP functions for performing integer +arithmetic. These functions start with the prefix `mpz_'. - - Function: void mpq_set_d (mpq_t ROP, double D) - Set ROP to the value of d, without rounding. + GMP integers are stored in objects of type `mpz_t'. - These functions assign between either the numerator or denominator -of a rational, and an integer. Instead of using these functions, it is -preferable to use the more general mechanisms `mpq_numref' and -`mpq_denref', together with `mpz_set'. +* Menu: - - Function: void mpq_set_num (mpq_t RATIONAL, mpz_t NUMERATOR) - Copy NUMERATOR to the numerator of RATIONAL. When this risks to - make the numerator and denominator of RATIONAL have common - factors, you have to pass RATIONAL to `mpq_canonicalize' before - any operations are performed on RATIONAL. +* Initializing Integers:: +* 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 equivalent to `mpz_set (mpq_numref (RATIONAL), - NUMERATOR)'. - - - Function: void mpq_set_den (mpq_t RATIONAL, mpz_t DENOMINATOR) - Copy DENOMINATOR to the denominator of RATIONAL. When this risks - to make the numerator and denominator of RATIONAL have common - factors, or if the denominator might be negative, you have to pass - RATIONAL to `mpq_canonicalize' before any operations are performed - on RATIONAL. - - *In version 1 of the library, negative denominators were handled by - copying the sign to the numerator. That is no longer done.* - - This function is equivalent to `mpz_set (mpq_denref (RATIONAL), - DENOMINATORS)'. - - - Function: void mpq_get_num (mpz_t NUMERATOR, mpq_t RATIONAL) - Copy the numerator of RATIONAL to the integer NUMERATOR, to - prepare for integer operations on the numerator. - - This function is equivalent to `mpz_set (NUMERATOR, mpq_numref - (RATIONAL))'. - - - Function: void mpq_get_den (mpz_t DENOMINATOR, mpq_t RATIONAL) - Copy the denominator of RATIONAL to the integer DENOMINATOR, to - prepare for integer operations on the denominator. - - This function is equivalent to `mpz_set (DENOMINATOR, mpq_denref - (RATIONAL))'. -  -File: gmp.info, Node: Floating-point Functions, Next: Low-level Functions, Prev: Rational Number Functions, Up: Top +File: gmp.info, Node: Initializing Integers, Next: Assigning Integers, Prev: Integer Functions, Up: Integer Functions -Floating-point Functions -************************ +Initialization Functions +======================== - This chapter describes the GMP functions for performing floating -point arithmetic. These functions start with the prefix `mpf_'. + The functions for integer arithmetic assume that all integer objects +are initialized. You do that by calling the function `mpz_init'. For +example, - GMP floating point numbers are stored in objects of type `mpf_t'. + { + mpz_t integ; + mpz_init (integ); + ... + mpz_add (integ, ...); + ... + mpz_sub (integ, ...); + + /* Unless the program is about to exit, do ... */ + mpz_clear (integ); + } - The GMP floating-point functions have an interface that is similar -to the GMP integer functions. The function prefix for floating-point -operations is `mpf_'. + As you can see, you can store new values any number of times, once an +object is initialized. - There is one significant characteristic of floating-point numbers -that has motivated a difference between this function class and other -GMP function classes: the inherent inexactness of floating point -arithmetic. The user has to specify the precision of each variable. A -computation that assigns a variable will take place with the precision -of the assigned variable; the precision of variables used as input is -ignored. + - Function: void mpz_init (mpz_t INTEGER) + Initialize INTEGER, and set its value to 0. - The precision of a calculation is defined as follows: Compute the -requested operation exactly (with "infinite precision"), and truncate -the result to the destination variable precision. Even if the user has -asked for a very high precision, GMP 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. + - Function: void mpz_init2 (mpz_t INTEGER, unsigned long N) + Initialize INTEGER, with space for N bits, and set its value to 0. - The GMP floating-point functions are _not_ intended as a smooth -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. + N is only the initial space, INTEGER will grow automatically in + 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. -* Menu: + - Function: void mpz_clear (mpz_t INTEGER) + Free the space occupied by INTEGER. Call this function for all + `mpz_t' variables when you are done with them. -* Initializing Floats:: -* Assigning Floats:: -* Simultaneous Float Init & Assign:: -* Converting Floats:: -* Float Arithmetic:: -* Float Comparison:: -* I/O of Floats:: -* Miscellaneous Float Functions:: + - Function: void mpz_realloc2 (mpz_t INTEGER, unsigned long N) + 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. - -File: gmp.info, Node: Initializing Floats, Next: Assigning Floats, Prev: Floating-point Functions, Up: Floating-point Functions + This function can be used to increase the space for a variable in + order to avoid repeated automatic reallocations, or to decrease it + to give memory back to the heap. -Initialization Functions -======================== + - Function: void mpz_array_init (mpz_t INTEGER_ARRAY[], size_t + 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. - - Function: void mpf_set_default_prec (unsigned long int PREC) - Set the default precision to be *at least* PREC bits. All - subsequent calls to `mpf_init' will use this precision, but - previously initialized variables are unaffected. + The space will not be automatically increased, unlike the normal + `mpz_init', but instead an application must ensure it's sufficient + for any value stored. The following space requirements apply to + various functions, - An `mpf_t' object must be initialized before storing the first value -in it. The functions `mpf_init' and `mpf_init2' are used for that -purpose. + * `mpz_abs', `mpz_neg', `mpz_set', `mpz_set_si' and + `mpz_set_ui' need room for the value they store. - - Function: void mpf_init (mpf_t X) - Initialize X to 0. Normally, a variable should be initialized - 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'. + * `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'. - - Function: void mpf_init2 (mpf_t X, unsigned long int PREC) - Initialize X to 0 and set its precision to be *at least* PREC - bits. Normally, a variable should be initialized once only or at - least be cleared, using `mpf_clear', between initializations. + * `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'. - - Function: void mpf_clear (mpf_t X) - Free the space occupied by X. Make sure to call this function for - all `mpf_t' variables when you are done with them. + * `mpz_swap' can be used between two array variables, but not + between an array and a normal variable. - Here is an example on how to initialize floating-point variables: - { - 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); - } + For other functions, or if in doubt, the suggestion is to + calculate in a regular `mpz_init' variable and copy the result to + an array variable with `mpz_set'. - The following three functions are useful for changing the precision -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. + `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: void mpf_set_prec (mpf_t ROP, unsigned long int PREC) - Set the precision of ROP to be *at least* PREC bits. Since - changing the precision involves calls to `realloc', this routine - should not be called in a tight loop. + - Function: void * _mpz_realloc (mpz_t INTEGER, mp_size_t NEW_ALLOC) + Change the space for INTEGER to NEW_ALLOC limbs. The value in + INTEGER is preserved if it fits, or is set to 0 if not. The return + value is not useful to applications and should be ignored. - - Function: unsigned long int mpf_get_prec (mpf_t OP) - Return the precision actually used for assignments of OP. + `mpz_realloc2' is the preferred way to accomplish allocation + changes like this. `mpz_realloc2' and `_mpz_realloc' are the same + except that `_mpz_realloc' takes the new size in limbs. - - Function: void mpf_set_prec_raw (mpf_t ROP, unsigned long int PREC) - Set the precision of ROP to be *at least* PREC bits. This is a - low-level function that does not change the allocation. The PREC - 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' - before the first call to `mpf_set_prec_raw'. -  -File: gmp.info, Node: Assigning Floats, Next: Simultaneous Float Init & Assign, Prev: Initializing Floats, Up: Floating-point Functions +File: gmp.info, Node: Assigning Integers, Next: Simultaneous Integer Init & Assign, Prev: Initializing Integers, Up: Integer Functions Assignment Functions ==================== - These functions assign new values to already initialized floats -(*note Initializing Floats::). + These functions assign new values to already initialized integers +(*note Initializing Integers::). - - Function: void mpf_set (mpf_t ROP, mpf_t OP) - - Function: void mpf_set_ui (mpf_t ROP, unsigned long int OP) - - 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) + - Function: void mpz_set (mpz_t ROP, mpz_t OP) + - 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: int mpf_set_str (mpf_t ROP, char *STR, int BASE) - Set the value of ROP from the string in STR. The string is of the - 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. + `mpz_set_d', `mpz_set_q' and `mpz_set_f' truncate OP to make it an + integer. - The argument BASE may be in the ranges 2 to 36, or -36 to -2. - Negative values are used to specify that the exponent is in - decimal. + - Function: int mpz_set_str (mpz_t ROP, char *STR, int BASE) + 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. - Unlike the corresponding `mpz' function, the base will not be - determined from the leading characters of the string if BASE is 0. - This is so that numbers like `0.23' are not interpreted as octal. + This function returns 0 if the entire string is a valid number in + base BASE. Otherwise it returns -1. - White space is allowed in the string, and is simply ignored. - [This is not really true; white-space is ignored in the beginning - of the string and within the mantissa, but not in other places, - such as after a minus sign or in the exponent. We are considering + [It turns out that it is not entirely true that this function + ignores white-space. It does ignore it between digits, but not + 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. Please tell us your opinion about this change. Do you - really want it to accept "3 14" as meaning 314 as it does now?] + sense. Send your opinion of this change to . Do + you really want it to accept "3 14" as meaning 314 as it does now?] - This function returns 0 if the entire string up to the '\0' is a - valid number in base BASE. Otherwise it returns -1. - - - Function: void mpf_swap (mpf_t ROP1, mpf_t ROP2) + - Function: void mpz_swap (mpz_t ROP1, mpz_t ROP2) Swap the values ROP1 and ROP2 efficiently.  -File: gmp.info, Node: Simultaneous Float Init & Assign, Next: Converting Floats, Prev: Assigning Floats, Up: Floating-point Functions +File: gmp.info, Node: Simultaneous Integer Init & Assign, Next: Converting Integers, Prev: Assigning Integers, Up: Integer Functions Combined Initialization and Assignment Functions ================================================ For convenience, GMP provides a parallel series of initialize-and-set functions which initialize the output and then store -the value there. These functions' names have the form `mpf_init_set...' +the value there. These functions' names have the form `mpz_init_set...' - Once the float has been initialized by any of the `mpf_init_set...' -functions, it can be used as the source or destination operand for the -ordinary float functions. Don't use an initialize-and-set function on -a variable already initialized! + Here is an example of using one: - - Function: void mpf_init_set (mpf_t ROP, mpf_t OP) - - Function: void mpf_init_set_ui (mpf_t ROP, unsigned long int OP) - - 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. + { + mpz_t pie; + mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10); + ... + mpz_sub (pie, ...); + ... + mpz_clear (pie); + } - The precision of ROP will be taken from the active default - precision, as set by `mpf_set_default_prec'. +Once the integer has been initialized by any of the `mpz_init_set...' +functions, it can be used as the source or destination operand for the +ordinary integer functions. Don't use an initialize-and-set function +on a variable already initialized! - - Function: int mpf_init_set_str (mpf_t ROP, char *STR, int BASE) - Initialize ROP and set its value from the string in STR. See - `mpf_set_str' above for details on the assignment operation. + - Function: void mpz_init_set (mpz_t ROP, mpz_t OP) + - Function: void mpz_init_set_ui (mpz_t ROP, unsigned long int OP) + - Function: void mpz_init_set_si (mpz_t ROP, signed long int OP) + - Function: void mpz_init_set_d (mpz_t ROP, double OP) + Initialize ROP with limb space and set the initial numeric value + from OP. - Note that ROP is initialized even if an error occurs. (I.e., you - have to call `mpf_clear' for it.) + - Function: int mpz_init_set_str (mpz_t ROP, char *STR, int BASE) + Initialize ROP and set its value like `mpz_set_str' (see its + documentation above for details). - The precision of ROP will be taken from the active default - precision, as set by `mpf_set_default_prec'. + If the string is a correct base BASE number, the function returns + 0; if an error occurs it returns -1. ROP is initialized even if + an error occurs. (I.e., you have to call `mpz_clear' for it.)  -File: gmp.info, Node: Converting Floats, Next: Float Arithmetic, Prev: Simultaneous Float Init & Assign, Up: Floating-point Functions +File: gmp.info, Node: Converting Integers, Next: Integer Arithmetic, Prev: Simultaneous Integer Init & Assign, Up: Integer Functions Conversion Functions ==================== - - Function: double mpf_get_d (mpf_t OP) - Convert OP to a double. + This section describes functions for converting GMP integers to +standard C types. Functions for converting _to_ GMP integers are +described in *Note Assigning Integers:: and *Note I/O of Integers::. - - Function: char * mpf_get_str (char *STR, mp_exp_t *EXPPTR, int BASE, - size_t N_DIGITS, mpf_t OP) - Convert OP to a string of digits in base BASE. The base may vary - from 2 to 36. Generate at most N_DIGITS significant digits, or if - N_DIGITS is 0, the maximum number of digits accurately - representable by OP. + - Function: unsigned long int mpz_get_ui (mpz_t OP) + Return the value of OP as an `unsigned long'. - If STR is `NULL', space for the mantissa is allocated using the - default allocation function. + If OP is too big to fit an `unsigned long' then just the least + significant bits that do fit are returned. The sign of OP is + ignored, only the absolute value is used. - If STR is not `NULL', it should point to a block of storage enough - large for the mantissa, i.e., N_DIGITS + 2. The two extra bytes - are for a possible minus sign, and for the terminating null - character. + - Function: signed long int mpz_get_si (mpz_t OP) + If OP fits into a `signed long int' return the value of OP. + Otherwise return the least significant part of OP, with the same + sign as OP. - The exponent is written through the pointer EXPPTR. + If OP is too big to fit in a `signed long int', the returned + result is probably not very useful. To find out if the value will + fit, use the function `mpz_fits_slong_p'. - If N_DIGITS is 0, the maximum number of digits meaningfully - achievable from the precision of OP will be generated. Note that - the space requirements for STR in this case will be impossible for - the user to predetermine. Therefore, you need to pass `NULL' for - the string argument whenever N_DIGITS is 0. + - Function: double mpz_get_d (mpz_t OP) + Convert OP to a `double'. - The generated string is a fraction, with an implicit radix point - immediately to the left of the first digit. For example, the - number 3.1416 would be returned as "31416" in the string and 1 - written at EXPPTR. + - Function: double mpz_get_d_2exp (signed long int *EXP, mpz_t OP) + Find D and EXP such that D times 2 raised to EXP, with + 0.5<=abs(D)<1, is a good approximation to OP. - A pointer to the result string is returned. This pointer will - will either equal STR, or if that is `NULL', will point to the - allocated storage. + - Function: char * mpz_get_str (char *STR, int BASE, mpz_t OP) + Convert OP to a string of digits in base BASE. The base may vary + from 2 to 36. + If STR is `NULL', the result string is allocated using the current + allocation function (*note Custom Allocation::). The block will be + `strlen(str)+1' bytes, that being exactly enough for the string and + null-terminator. + + If STR is not `NULL', it should point to a block of storage large + enough for the result, that being `mpz_sizeinbase (OP, BASE) + 2'. + The two extra bytes are for a possible minus sign, and the + null-terminator. + + A pointer to the result string is returned, being either the + allocated block, or the given STR. + + - Function: mp_limb_t mpz_getlimbn (mpz_t OP, mp_size_t N) + Return limb number N from OP. The sign of OP is ignored, just the + absolute value is used. The least significant limb is number 0. + + `mpz_size' can be used to find how many limbs make up OP. + `mpz_getlimbn' returns zero if N is outside the range 0 to + `mpz_size(OP)-1'. +  -File: gmp.info, Node: Float Arithmetic, Next: Float Comparison, Prev: Converting Floats, Up: Floating-point Functions +File: gmp.info, Node: Integer Arithmetic, Next: Integer Division, Prev: Converting Integers, Up: Integer Functions Arithmetic Functions ==================== - - Function: void mpf_add (mpf_t ROP, mpf_t OP1, mpf_t OP2) - - Function: void mpf_add_ui (mpf_t ROP, mpf_t OP1, unsigned long int + - Function: void mpz_add (mpz_t ROP, mpz_t OP1, mpz_t OP2) + - Function: void mpz_add_ui (mpz_t ROP, mpz_t OP1, unsigned long int OP2) Set ROP to OP1 + OP2. - - Function: void mpf_sub (mpf_t ROP, mpf_t OP1, mpf_t OP2) - - Function: void mpf_ui_sub (mpf_t ROP, unsigned long int OP1, mpf_t + - Function: void mpz_sub (mpz_t ROP, mpz_t OP1, mpz_t OP2) + - Function: void mpz_sub_ui (mpz_t ROP, mpz_t OP1, unsigned long int OP2) - - Function: void mpf_sub_ui (mpf_t ROP, mpf_t OP1, unsigned long int + - Function: void mpz_ui_sub (mpz_t ROP, unsigned long int OP1, mpz_t OP2) Set ROP to OP1 - OP2. - - Function: void mpf_mul (mpf_t ROP, mpf_t OP1, mpf_t OP2) - - Function: void mpf_mul_ui (mpf_t ROP, mpf_t OP1, unsigned long int + - Function: void mpz_mul (mpz_t ROP, mpz_t OP1, mpz_t OP2) + - Function: void mpz_mul_si (mpz_t ROP, mpz_t OP1, long int OP2) + - Function: void mpz_mul_ui (mpz_t ROP, mpz_t OP1, unsigned long int OP2) Set ROP to OP1 times OP2. - Division is undefined if the divisor is zero, and passing a zero -divisor to the divide functions will make these functions intentionally -divide by zero. This lets the user handle arithmetic exceptions in -these functions in the same manner as other arithmetic exceptions. + - Function: void mpz_addmul (mpz_t ROP, mpz_t OP1, mpz_t OP2) + - Function: void mpz_addmul_ui (mpz_t ROP, mpz_t OP1, unsigned long + int OP2) + Set ROP to ROP + OP1 times OP2. - - Function: void mpf_div (mpf_t ROP, mpf_t OP1, mpf_t OP2) - - Function: void mpf_ui_div (mpf_t ROP, unsigned long int OP1, mpf_t - OP2) - - Function: void mpf_div_ui (mpf_t ROP, mpf_t OP1, unsigned long int - OP2) - Set ROP to OP1/OP2. + - 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 mpf_sqrt (mpf_t ROP, mpf_t OP) - - Function: void mpf_sqrt_ui (mpf_t ROP, unsigned long int OP) - Set ROP to the square root of OP. - - - Function: void mpf_pow_ui (mpf_t ROP, mpf_t OP1, unsigned long int + - Function: void mpz_mul_2exp (mpz_t ROP, mpz_t OP1, unsigned long int OP2) - Set ROP to OP1 raised to the power OP2. + Set ROP to OP1 times 2 raised to OP2. This operation can also be + defined as a left shift by OP2 bits. - - Function: void mpf_neg (mpf_t ROP, mpf_t OP) + - Function: void mpz_neg (mpz_t ROP, mpz_t OP) Set ROP to -OP. - - Function: void mpf_abs (mpf_t ROP, mpf_t OP) + - Function: void mpz_abs (mpz_t ROP, mpz_t OP) Set ROP to the absolute value of OP. - - Function: void mpf_mul_2exp (mpf_t ROP, mpf_t OP1, unsigned long int - OP2) - Set ROP to OP1 times 2 raised to OP2. + +File: gmp.info, Node: Integer Division, Next: Integer Exponentiation, Prev: Integer Arithmetic, Up: Integer Functions - - Function: void mpf_div_2exp (mpf_t ROP, mpf_t OP1, unsigned long int - OP2) - Set ROP to OP1 divided by 2 raised to OP2. +Division Functions +================== - -File: gmp.info, Node: Float Comparison, Next: I/O of Floats, Prev: Float Arithmetic, Up: Floating-point Functions + Division is undefined if the divisor is zero. Passing a zero +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. -Comparison Functions -==================== + - Function: void mpz_cdiv_q (mpz_t Q, mpz_t N, mpz_t D) + - 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) - - Function: int mpf_cmp (mpf_t OP1, mpf_t OP2) - - Function: int mpf_cmp_ui (mpf_t OP1, unsigned long int OP2) - - Function: int mpf_cmp_si (mpf_t OP1, signed long int OP2) - Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero - if OP1 = OP2, and a negative value if OP1 < OP2. + - 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) - - Function: int mpf_eq (mpf_t OP1, mpf_t OP2, unsigned long int op3) - Return non-zero if the first OP3 bits of OP1 and OP2 are equal, - zero otherwise. I.e., test of OP1 and OP2 are approximately equal. + - Function: void mpz_tdiv_q (mpz_t Q, mpz_t N, mpz_t D) + - Function: void mpz_tdiv_r (mpz_t R, mpz_t N, mpz_t D) + - Function: void mpz_tdiv_qr (mpz_t Q, mpz_t R, mpz_t N, mpz_t D) + - 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) - - Function: void mpf_reldiff (mpf_t ROP, mpf_t OP1, mpf_t OP2) - Compute the relative difference between OP1 and OP2 and store the - result in ROP. + Divide N by D, forming a quotient Q and/or remainder R. For the + `2exp' functions, D=2^B. The rounding is in three styles, each + suiting different applications. - - Macro: int mpf_sgn (mpf_t OP) - Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0. + * `cdiv' rounds Q up towards +infinity, and R will have the + opposite sign to D. The `c' stands for "ceil". - This function is actually implemented as a macro. It evaluates its - arguments multiple times. + * `fdiv' rounds Q down towards -infinity, and R will have the + same sign as D. The `f' stands for "floor". - -File: gmp.info, Node: I/O of Floats, Next: Miscellaneous Float Functions, Prev: Float Comparison, Up: Floating-point Functions + * `tdiv' rounds Q towards zero, and R will have the same sign + as N. The `t' stands for "truncate". -Input and Output Functions -========================== + In all cases Q and R will satisfy N=Q*D+R, and R will satisfy + 0<=abs(R)1, such that OP equals A raised to the + power B. + + Under this definition both 0 and 1 are considered to be perfect + powers. Negative values of OP are accepted, but of course can + only be odd perfect powers. + + - Function: int mpz_perfect_square_p (mpz_t OP) + Return non-zero if OP is a perfect square, i.e., if the square + root of OP is an integer. Under this definition both 0 and 1 are + considered to be perfect squares.