=================================================================== RCS file: /home/cvs/OpenXM_contrib/gmp/Attic/gmp.info-2,v retrieving revision 1.1 retrieving revision 1.1.1.4 diff -u -p -r1.1 -r1.1.1.4 --- OpenXM_contrib/gmp/Attic/gmp.info-2 2000/01/10 15:35:21 1.1 +++ OpenXM_contrib/gmp/Attic/gmp.info-2 2003/08/25 16:06:02 1.1.1.4 @@ -1,1035 +1,1212 @@ -This is Info file gmp.info, produced by Makeinfo-1.64 from the input -file 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.info). GNU Multiple Precision Arithmetic Library. +* gmp: (gmp). GNU Multiple Precision Arithmetic Library. 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, -Inc. +Parameter Conventions +===================== - 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. + 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. - 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. + 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. - 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. + Here's an example accepting an `mpz_t' parameter, doing a +calculation, and storing the result to the indicated parameter. + 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 -floating-point arithmetic in GNU MP 2. + 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. - 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 -the MP integer functions. The function prefix for floating-point -operations is `mpf_'. + `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. - There is one significant characteristic of floating-point numbers -that has motivated a difference between this function class and other -MP 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. + 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::. - 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, 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. + +File: gmp.info, Node: Reentrancy, Next: Useful Macros and Constants, Prev: Memory Management, Up: GMP Basics - The MP 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. +Reentrancy +========== -* Menu: + GMP is reentrant and thread-safe, with some exceptions: -* Initializing Floats:: -* Assigning Floats:: -* Simultaneous Float Init & Assign:: -* Converting Floats:: -* Float Arithmetic:: -* Float Comparison:: -* I/O of Floats:: -* Miscellaneous Float Functions:: + * If configured with `--enable-alloca=malloc-notreentrant' (or with + `--enable-alloca=notreentrant' when `alloca' is not available), + then naturally GMP is not reentrant. - -File: gmp.info, Node: Initializing Floats, Next: Assigning Floats, Up: Floating-point Functions + * `mpf_set_default_prec' and `mpf_init' use a global variable for the + 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) - 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. + * `mp_set_memory_functions' uses global variables to store the + selected memory allocation 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. + * 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. - - 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'. + * 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 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. + * 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. - - 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. + * 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. - 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); - } + +File: gmp.info, Node: Useful Macros and Constants, Next: Compatibility with older versions, Prev: Reentrancy, Up: GMP Basics - 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. +Useful Macros and Constants +=========================== - - 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. + - Global Constant: const int mp_bits_per_limb + The number of bits per limb. - - Function: unsigned long int mpf_get_prec (mpf_t OP) - Return the precision actually used for assignments of OP. + - 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 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'. + - 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: 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 -(*note Initializing Floats::.). + 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 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) - Set the value of ROP from OP. + * `mpn_gcd' had its source arguments swapped as of GMP 3.0, for + consistency with other `mpn' functions. - - 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. + * `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. - 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. + 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. - 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. + The Berkeley MP compatibility library (*note BSD Compatible +Functions::) is source and binary compatible with the standard `libmp'. - 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 - valid number in base BASE. Otherwise it returns -1. +Demonstration programs +====================== - -File: gmp.info, Node: Simultaneous Float Init & Assign, Next: Converting Floats, Prev: Assigning Floats, Up: Floating-point Functions + 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, -Combined Initialization and Assignment Functions ------------------------------------------------- + make pexpr + ./pexpr 68^975+10 - For convenience, MP 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 following programs are provided - 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! + * `pexpr' is an expression evaluator, the program used on the GMP + web page. - - 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. + * The `calc' subdirectory has a similar but simpler evaluator using + `lex' and `yacc'. - The precision of ROP will be taken from the active default - precision, as set by `mpf_set_default_prec'. + * 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. - - 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. + * `factorize' is a Pollard-Rho factorization program. - Note that ROP is initialized even if an error occurs. (I.e., you - have to call `mpf_clear' for it.) + * `isprime' is a command-line interface to the `mpz_probab_prime_p' + function. - The precision of ROP will be taken from the active default - precision, as set by `mpf_set_default_prec'. + * `primes' counts or lists primes in an interval, using a sieve. + * `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) - Convert OP to a double. +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: 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. +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. - If STR is NULL, space for the mantissa is allocated using the - default allocation function, and a pointer to the string is - returned. +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. - 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. + 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. - 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 - 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. + 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. - 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. +`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. - -File: gmp.info, Node: Float Arithmetic, Next: Float Comparison, Prev: Converting Floats, Up: Floating-point Functions +`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. -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) - - Function: void mpf_add_ui (mpf_t ROP, mpf_t OP1, unsigned long int - OP2) - Set ROP to OP1 + OP2. + `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. - - 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 - OP2) - - Function: void mpf_sub_ui (mpf_t ROP, mpf_t OP1, unsigned long int - OP2) - Set ROP to OP1 - OP2. + `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. - - 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 - OP2) - Set ROP to OP1 times OP2. + `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. - 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 gives the user the possibility to handle -arithmetic exceptions in these functions in the same manner as other -arithmetic exceptions. + if (x != y) + mpz_set (x, y); - - 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. + 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 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. +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 mpf_neg (mpf_t ROP, mpf_t OP) - Set ROP to -OP. + 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 mpf_abs (mpf_t ROP, mpf_t OP) - Set ROP to the absolute value of OP. + 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 mpf_mul_2exp (mpf_t ROP, mpf_t OP1, unsigned long int - OP2) - Set ROP to OP1 times 2 raised to OP2. +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: void mpf_div_2exp (mpf_t ROP, mpf_t OP1, unsigned long int - OP2) - Set ROP to OP1 divided by 2 raised to OP2. + 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. + 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) - - 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. +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. - - 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. + 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: 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. +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. - - Macro: int mpf_sgn (mpf_t OP) - Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 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 - This function is actually implemented as a macro. It evaluates its - arguments multiple times. + `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' - -File: gmp.info, Node: I/O of Floats, Next: Miscellaneous Float Functions, Prev: Float Comparison, Up: Floating-point Functions + 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. -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 -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. +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. - 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. +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. - - Function: size_t mpf_out_str (FILE *STREAM, int BASE, size_t - N_DIGITS, mpf_t OP) - 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. + cd /my/build/dir + /my/source/dir/gmp-4.1.2/configure - In addition to the significant digits, a leading `0.' and a - trailing exponent, in the form `eNNN', are printed. If BASE is - greater than 10, `@' will be used instead of `e' as exponent - delimiter. + This works via `VPATH', and might require GNU `make'. Alternately + it might be possible to change the `.c.lo' rules appropriately. - Return the number of bytes written, or if an error occurred, - return 0. +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. - - Function: size_t mpf_inp_str (mpf_t ROP, FILE *STREAM, int BASE) - Input a string in base BASE from stdio stream STREAM, and put the - read float in ROP. 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. + 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. - 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. +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'). - 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 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. - 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 - -File: gmp.info, Node: Miscellaneous Float Functions, Prev: I/O of Floats, Up: Floating-point Functions + ./configure --disable-shared --enable-assert \ + --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 - MAX_EXP) - Generate a random float of at most MAX_SIZE limbs, with long - strings of zeros and ones in the binary representation. The - 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. +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. + 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 -high-level MP functions, but also intended for time-critical user code. + 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. - 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 -provide a coherent calling interface. The different functions have -somewhat similar interfaces, but there are variations that make them -hard to use. These functions do as little as possible apart from the -real multiple precision computation, so that no time is spent on things -that not all callers need. + 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. - A source operand is specified by a pointer to the least significant -limb and a limb count. A destination operand is specified by just a -pointer. It is the responsibility of the caller to ensure that the -destination has enough space for storing the result. + 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. - With this way of specifying operands, it is possible to perform -computations on subranges of an argument, and store the result into a -subrange of a destination. + 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. - 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_', -`mpf_', and `mpq_' functions. +Autoconf +======== - This example adds the number beginning at SRC1_PTR and the number -beginning at SRC2_PTR and writes the sum at DEST_PTR. All areas have -SIZE limbs. + 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, - 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 -pointer to the least significant limb, and the limb count in braces. -For example, {s1_ptr, s1_size}. + 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, - - Function: mp_limb_t mpn_add_n (mp_limb_t * DEST_PTR, const mp_limb_t - * SRC1_PTR, const mp_limb_t * SRC2_PTR, mp_size_t SIZE) - 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. + AC_CHECK_LIB(gmp, __gmpz_init, , [AC_MSG_ERROR( + [GNU MP not found, see http://swox.com/gmp])]) - This is the lowest-level function for addition. It is the - preferred function for addition, since it is written in assembly - for most targets. For addition of a variable to itself (i.e., - SRC1_PTR equals SRC2_PTR, use `mpn_lshift' with a count of 1 for - optimal speed. + 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, - - Function: mp_limb_t mpn_add_1 (mp_limb_t * DEST_PTR, const mp_limb_t - * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB) - 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. + 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])]) - - Function: mp_limb_t mpn_add (mp_limb_t * DEST_PTR, const mp_limb_t * - SRC1_PTR, mp_size_t SRC1_SIZE, const mp_limb_t * SRC2_PTR, - mp_size_t SRC2_SIZE) - 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. + 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. - This function requires that SRC1_SIZE is greater than or equal to - SRC2_SIZE. + 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, - - Function: mp_limb_t mpn_sub_n (mp_limb_t * DEST_PTR, const mp_limb_t - * SRC1_PTR, const mp_limb_t * SRC2_PTR, mp_size_t SIZE) - Subtract {SRC2_PTR, SRC2_SIZE} from {SRC1_PTR, SIZE}, and write - the SIZE least significant limbs of the result to DEST_PTR. - Return borrow, either 0 or 1. + AC_CHECK_LIB(gmp, __gmpz_init, , + [AC_CHECK_LIB(gmp, mpz_init, , + [AC_CHECK_LIB(gmp2, mpz_init)])]) - This is the lowest-level function for subtraction. It is the - preferred function for subtraction, since it is written in - assembly for most targets. + 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: mp_limb_t mpn_sub_1 (mp_limb_t * DEST_PTR, const mp_limb_t - * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB) - Subtract SRC2_LIMB from {SRC1_PTR, SIZE}, and write the SIZE least - significant limbs of the result to DEST_PTR. Return borrow, - either 0 or 1. + 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: mp_limb_t mpn_sub (mp_limb_t * DEST_PTR, const mp_limb_t * - 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. + AC_CHECK_SIZEOF(mp_limb_t, , [#include ]) - This function requires that SRC1_SIZE is greater than or equal to - SRC2_SIZE. + 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 mpn_mul_n (mp_limb_t * DEST_PTR, const mp_limb_t * - SRC1_PTR, const mp_limb_t * SRC2_PTR, mp_size_t SIZE) - Multiply {SRC1_PTR, SIZE} and {SRC2_PTR, SIZE}, and write the - *entire* result to DEST_PTR. + 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]) - 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 - * 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. +Emacs +===== - This is a low-level function that is a building block for general - multiplication as well as other operations in MP. It is written - in assembly for most targets. + (`info-lookup-symbol') is a good way to find documentation +on C functions while editing (*note Info Documentation Lookup: +(emacs)Info Lookup.). - Don't call this function if SRC2_LIMB is a power of 2; use - `mpn_lshift' with a count equal to the logarithm of SRC2_LIMB - instead, for optimal speed. + The GMP manual can be included in such lookups by putting the +following in your `.emacs', - - Function: mp_limb_t mpn_addmul_1 (mp_limb_t * DEST_PTR, const - mp_limb_t * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB) - Multiply {SRC1_PTR, SIZE} and SRC2_LIMB, and add the SIZE least - significant limbs of the product to {DEST_PTR, SIZE} and write the - result to DEST_PTR DEST_PTR. Return the most significant limb of - the product, plus carry-out from the addition. + (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))))) - This is a low-level function that is a building block for general - multiplication as well as other operations in MP. It is written - in assembly for most targets. + The same can be done for MPFR, with `(mpfr)' in place of `(gmp)'. - - 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) - 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. + +File: gmp.info, Node: Reporting Bugs, Next: Integer Functions, Prev: GMP Basics, Up: Top - This is a low-level function that is a building block for general - multiplication and division as well as other operations in MP. It - is written in assembly for most targets. +Reporting Bugs +************** - - Function: mp_limb_t mpn_mul (mp_limb_t * DEST_PTR, const mp_limb_t * - SRC1_PTR, mp_size_t SRC1_SIZE, const mp_limb_t * SRC2_PTR, - mp_size_t SRC2_SIZE) - 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. + 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. - The destination has to have space for SRC1_SIZE + SRC1_SIZE limbs, - even if the result might be one limb smaller. + 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. - This function requires that SRC1_SIZE is greater than or equal to - SRC2_SIZE. The destination must be distinct from either input - operands. + Please include the following in any report, - - Function: mp_size_t mpn_divrem (mp_limb_t * R1P, mp_size_t XSIZE, - 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. + * The GMP version number, and if pre-packaged or patched then say so. - In addition to an integer quotient, XSIZE fraction limbs are - developed, and stored after the integral limbs. For most usages, - XSIZE will be zero. + * A test program that makes it possible for us to reproduce the bug. + Include instructions on how to run the program. - It is required that RS2SIZE is greater than or equal to S3SIZE. - It is required that the most significant bit of the divisor is set. + * A description of what is wrong. If the results are incorrect, in + what way. If you get a crash, say so. - If the quotient is not needed, pass RS2P + S3SIZE as R1P. Aside - from that special case, no overlap between arguments is permitted. + * If you get a crash, include a stack backtrace from the debugger if + 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, - mp_limb_t * S2P, mp_size_t S2SIZE, mp_limb_t S3LIMB) - Divide {S2P, S2SIZE} by S3LIMB, and write the quotient at R1P. - Return the remainder. + * The name of the compiler and its version. For `gcc', get the + version with `gcc -v', otherwise perhaps `what `which cc`', or + similar. - In addition to an integer quotient, XSIZE fraction limbs are - developed, and stored after the integral limbs. For most usages, - XSIZE will be zero. + * The output from running `uname -a'. - The areas at R1P and S2P have to be identical or completely - separate, not partially overlapping. + * The output from running `./config.guess', and from running + `./configfsf.guess' (might be the same). - - Function: mp_size_t mpn_divmod (mp_limb_t * R1P, mp_limb_t * RS2P, - mp_size_t RS2SIZE, const mp_limb_t * S3P, mp_size_t S3SIZE) - *This interface is obsolete. It will disappear from future - releases. Use `mpn_divrem' in its stead.* + * If the bug is related to `configure', then the contents of + `config.log'. - - Function: mp_limb_t mpn_divmod_1 (mp_limb_t * R1P, mp_limb_t * S2P, - mp_size_t S2SIZE, mp_limb_t S3LIMB) - *This interface is obsolete. It will disappear from future - releases. Use `mpn_divrem_1' in its stead.* + * 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'. - - Function: mp_limb_t mpn_mod_1 (mp_limb_t * S1P, mp_size_t S1SIZE, - mp_limb_t S2LIMB) - Divide {S1P, S1SIZE} by S2LIMB, and return the remainder. + 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. - - Function: mp_limb_t mpn_preinv_mod_1 (mp_limb_t * S1P, mp_size_t - S1SIZE, mp_limb_t S2LIMB, mp_limb_t S3LIMB) - *This interface is obsolete. It will disappear from future - releases. Use `mpn_mod_1' in its stead.* + 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: mp_limb_t mpn_bdivmod (mp_limb_t * DEST_PTR, mp_limb_t * - S1P, mp_size_t S1SIZE, const mp_limb_t * S2P, mp_size_t - S2SIZE, unsigned long int D) - 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. + 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). - {S1P, S1SIZE} - Q * {S2P, S2SIZE} mod 2^(S1SIZE*BITS_PER_MP_LIMB) - 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. + Send your report to: . - This function requires that S1SIZE * BITS_PER_MP_LIMB >= D, and - that {S2P, S2SIZE} is odd. + 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. - *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 - 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. +Integer Functions +***************** - Overlapping of the destination space and the source space is - allowed in this function, provided DEST_PTR >= SRC_PTR. + This chapter describes the GMP functions for performing integer +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 - 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. +* Menu: - Overlapping of the destination space and the source space is - allowed in this function, provided DEST_PTR <= SRC_PTR. +* 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 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 * - 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. +Initialization Functions +======================== - - Function: mp_size_t mpn_gcd (mp_limb_t * DEST_PTR, mp_limb_t * - SRC1_PTR, mp_size_t SRC1_SIZE, mp_limb_t * SRC2_PTR, - mp_size_t SRC2_SIZE) - 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. + The functions for integer arithmetic assume that all integer objects +are initialized. You do that by calling the function `mpz_init'. For +example, - {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 - future revisions.* + As you can see, you can store new values any number of times, once an +object is initialized. - - Function: mp_limb_t mpn_gcd_1 (const mp_limb_t * SRC1_PTR, mp_size_t - SRC1_SIZE, mp_limb_t SRC2_LIMB) - 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: void mpz_init (mpz_t INTEGER) + Initialize INTEGER, and set its value to 0. - - Function: mp_size_t mpn_gcdext (mp_limb_t * R1P, mp_limb_t * R2P, - mp_limb_t * S1P, mp_size_t S1SIZE, mp_limb_t * S2P, mp_size_t - 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. + - Function: void mpz_init2 (mpz_t INTEGER, unsigned long N) + Initialize INTEGER, with space for N bits, and set its value to 0. - *This interface is preliminary. It might change incompatibly in - future revisions.* + 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. - - Function: mp_size_t mpn_sqrtrem (mp_limb_t * R1P, mp_limb_t * R2P, - const mp_limb_t * SP, mp_size_t SIZE) - Compute the square root of {SP, SIZE} and put the result at R1P. - Write the remainder at R2P, unless R2P is NULL. + - 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. - Return the size of the remainder, whether R2P was NULL or non-NULL. - Iff the operand was a perfect square, the return value will be 0. + - 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. - The areas at R1P and SP have to be distinct. The areas at R2P and - SP have to be identical or completely separate, not partially - overlapping. + 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. - The area at R1P needs to have space for ceil(SIZE/2) limbs. The - area at R2P needs to be SIZE limbs large. + - 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. - *This interface is preliminary. It might change incompatibly in - future revisions.* + 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, - - Function: mp_size_t mpn_get_str (unsigned char *STR, int BASE, - mp_limb_t * S1P, mp_size_t S1SIZE) - 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. + * `mpz_abs', `mpz_neg', `mpz_set', `mpz_set_si' and + `mpz_set_ui' need room for the value they store. - 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 - represented by a S1SIZE long limb array, plus one extra character. + * `mpz_swap' can be used between two array variables, but not + between an array and a normal variable. - - Function: mp_size_t mpn_set_str (mp_limb_t * R1P, const char *STR, - size_t strsize, int BASE) - Convert the raw unsigned char array at STR of length STRSIZE to a - limb array {S1P, S1SIZE}. The base of STR is BASE. + 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'. - 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, - unsigned long int BIT) - Scan S1P from bit position BIT for the next clear bit. + - 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. - It is required that there be a clear bit within the area at S1P at - or beyond bit position BIT, so that the function has something to - return. + `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. - *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, - unsigned long int BIT) - Scan S1P from bit position BIT for the next set bit. +Assignment Functions +==================== - It is required that there be a set bit within the area at S1P at or - beyond bit position BIT, so that the function has something to - return. + These functions assign new values to already initialized integers +(*note Initializing Integers::). - *This interface is preliminary. It might change incompatibly in - future revisions.* + - 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: void mpn_random2 (mp_limb_t * R1P, mp_size_t R1SIZE) - Generate a random number of length R1SIZE with long strings of - zeros and ones in the binary representation, and store it at R1P. + `mpz_set_d', `mpz_set_q' and `mpz_set_f' truncate OP to make it an + integer. - The generated random numbers are intended for testing the - correctness of the implementation of the `mpn' routines. + - 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. - - Function: unsigned long int mpn_popcount (const mp_limb_t * S1P, - unsigned long int SIZE) - Count the number of set bits in {S1P, SIZE}. + This function returns 0 if the entire string is a valid number in + base BASE. Otherwise it returns -1. - - Function: unsigned long int mpn_hamdist (const mp_limb_t * S1P, - const mp_limb_t * S2P, unsigned long int SIZE) - Compute the hamming distance between {S1P, SIZE} and {S2P, SIZE}. + [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. Send your opinion of this change to . 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 - SIZE) - Return non-zero iff {S1P, SIZE} is a perfect square. + - Function: void mpz_swap (mpz_t ROP1, mpz_t ROP2) + Swap the values ROP1 and ROP2 efficiently.  -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 -Berkeley MP library which is available on many BSD derived U*ix systems. + 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 `mpz_init_set...' - The original Berkeley MP library has a usage restriction: you cannot -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. + Here is an example of using one: - It is not recommended that new programs are written using these -functions. Apart from the incomplete set of functions, the interface -for initializing `MINT' objects is more error prone, and the `pow' -function collides with `pow' in `libm.a'. + { + mpz_t pie; + mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10); + ... + mpz_sub (pie, ...); + ... + mpz_clear (pie); + } - Include the header `mp.h' to get the definition of the necessary -types and functions. If you are on a BSD derived system, make sure to -include GNU `mp.h' if you are going to link the GNU `libmp.a' to you -program. This means that you probably need to give the -I option -to the compiler, where is the directory where you have GNU `mp.h'. +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: MINT * itom (signed short int INITIAL_VALUE) - Allocate an integer consisting of a `MINT' object and dynamic limb - space. Initialize the integer to INITIAL_VALUE. Return a pointer - to the `MINT' object. + - 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. - - Function: MINT * xtom (char *INITIAL_VALUE) - Allocate an integer consisting of a `MINT' object and dynamic limb - space. Initialize the integer from INITIAL_VALUE, a hexadecimal, - '\0'-terminate C string. Return a pointer to the `MINT' object. + - 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). - - Function: void move (MINT *SRC, MINT *DEST) - Set DEST to SRC by copying. Both variables must be previously - initialized. + 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.) - - 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) - Subtract SRC_2 from SRC_1 and put the difference in DESTINATION. +Conversion Functions +==================== - - Function: void mult (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION) - Multiply SRC_1 and SRC_2 and put the product in DESTINATION. + 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: void mdiv (MINT *DIVIDEND, MINT *DIVISOR, MINT *QUOTIENT, - MINT *REMAINDER) - - 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. + - Function: unsigned long int mpz_get_ui (mpz_t OP) + Return the value of OP as an `unsigned long'. - Some implementations of these functions work differently--or not - at all--for negative arguments. + 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. - - Function: void msqrt (MINT *OPERAND, MINT *ROOT, MINT *REMAINDER) - Set ROOT to the truncated integer part of the square root of - OPERAND. Set REMAINDER to OPERAND-ROOT*ROOT, (i.e., zero if - OPERAND is a perfect square). + - 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. - If ROOT and REMAINDER are the same variable, the results are - undefined. + 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'. - - Function: void pow (MINT *BASE, MINT *EXP, MINT *MOD, MINT *DEST) - Set DEST to (BASE raised to EXP) modulo MOD. + - Function: double mpz_get_d (mpz_t OP) + Convert OP to a `double'. - - Function: void rpow (MINT *BASE, signed short int EXP, MINT *DEST) - Set DEST to BASE raised to EXP. + - 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. - - Function: void gcd (MINT *OPERAND1, MINT *OPERAND2, MINT *RES) - Set RES to the greatest common divisor of OPERAND1 and OPERAND2. + - 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. - - Function: int mcmp (MINT *OPERAND1, MINT *OPERAND2) - Compare OPERAND1 and OPERAND2. Return a positive value if - OPERAND1 > OPERAND2, zero if OPERAND1 = OPERAND2, and a negative - value if OPERAND1 < OPERAND2. + 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. - - Function: void min (MINT *DEST) - Input a decimal string from `stdin', and put the read integer in - DEST. SPC and TAB are allowed in the number string, and are - ignored. + 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. - - Function: void mout (MINT *SRC) - Output SRC to `stdout', as a decimal string. Also output a - newline. + A pointer to the result string is returned, being either the + allocated block, or the given STR. - - Function: char * mtox (MINT *OPERAND) - Convert OPERAND to a hexadecimal string, and return a pointer to - the string. The returned string is allocated using the default - memory allocation function, `malloc' by default. + - 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. - - Function: void mfree (MINT *OPERAND) - De-allocate, the space used by OPERAND. *This function should - only be passed a value returned by `itom' or `xtom'.* + `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: 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 -memory allocation. If `malloc' or `realloc' fails, the MP library -terminates execution after printing a fatal error message to standard -error. + - 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. - For some applications, you may wish to allocate memory in other -ways, or you may not want to have a fatal error when there is no more -memory available. To accomplish this, you can specify alternative -memory allocation functions. + - 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 mpz_ui_sub (mpz_t ROP, unsigned long int OP1, mpz_t + OP2) + Set ROP to OP1 - OP2. - - Function: void mp_set_memory_functions ( - void *(*ALLOC_FUNC_PTR) (size_t), - void *(*REALLOC_FUNC_PTR) (void *, size_t, size_t), - void (*FREE_FUNC_PTR) (void *, size_t)) - Replace the current allocation functions from the arguments. If - an argument is NULL, the corresponding default function is - retained. + - 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. - *Make sure to call this function in such a way that there are no - active MP objects that were allocated using the previously active - allocation function! Usually, that means that you have to call - this function before any other MP function.* + - 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. - 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) - This function should return a pointer to newly allocated space - with at least ALLOC_SIZE storage units. + - Function: void mpz_mul_2exp (mpz_t ROP, mpz_t OP1, unsigned long int + 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 * reallocate_function (void *PTR, size_t OLD_SIZE, - size_t NEW_SIZE) - 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. + - Function: void mpz_neg (mpz_t ROP, mpz_t OP) + Set ROP to -OP. - You can assume that the space at PTR was formerly returned from - `allocate_function' or `reallocate_function', for a request for - OLD_SIZE storage units. + - Function: void mpz_abs (mpz_t ROP, mpz_t OP) + Set ROP to the absolute value of OP. - - 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 - `allocate_function' or `reallocate_function', for a request for - SIZE storage units. +Division Functions +================== - (A "storage unit" is the unit in which the `sizeof' operator returns -the size of an object, normally an 8 bit byte.) + 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. - -File: gmp.info, Node: Contributors, Next: References, Prev: Custom Allocation, Up: Top + - 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) -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 -with mathematical problems, Richard Stallman for his help with design -issues and for revising the first version of this manual, Brian Beuning -and Doug Lea for their testing of early versions of the library. + - 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) - John Amanatides of York University in Canada contributed the function -`mpz_probab_prime_p'. + 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. - Paul Zimmermann of Inria sparked the development of GMP 2, with his -comparisons between bignum packages. + * `cdiv' rounds Q up towards +infinity, and R will have the + opposite sign to D. The `c' stands for "ceil". - Ken Weber (Kent State University, Universidade Federal do Rio Grande -do Sul) contributed `mpz_gcd', `mpz_divexact', `mpn_gcd', and -`mpn_bdivmod', partially supported by CNPq (Brazil) grant 301314194-2. + * `fdiv' rounds Q down towards -infinity, and R will have the + same sign as D. The `f' stands for "floor". - Per Bothner of Cygnus Support helped to set up MP to use Cygnus' -configure. He has also made valuable suggestions and tested numerous -intermediary releases. + * `tdiv' rounds Q towards zero, and R will have the same sign + as N. The `t' stands for "truncate". - Joachim Hollman was involved in the design of the `mpf' interface, -and in the `mpz' design revisions for version 2. + In all cases Q and R will satisfy N=Q*D+R, and R will satisfy + 0<=abs(R): Float Arithmetic. -* Arithmetic functions: Integer Arithmetic. -* Bit manipulation functions: Integer Logic and Bit Fiddling. -* BSD MP compatible functions: BSD Compatible Functions. -* Comparison functions: Float Comparison. -* Conditions for copying GNU MP: Copying. -* Conversion functions <1>: Converting Integers. -* Conversion functions: Converting Floats. -* Copying conditions: Copying. -* Float arithmetic functions: Float Arithmetic. -* Float assignment functions: Assigning Floats. -* Float comparisons functions: Float Comparison. -* Float functions: Floating-point Functions. -* Float input and output functions: I/O of Floats. -* Floating-point functions: Floating-point Functions. -* Floating-point number: MP Basics. -* I/O functions <1>: I/O of Floats. -* I/O functions: I/O of Integers. -* Initialization and assignment functions <1>: Simultaneous Float Init & Assign. -* Initialization and assignment functions: Simultaneous Integer Init & Assign. -* Input functions <1>: I/O of Integers. -* 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. + - Function: void mpz_sqrt (mpz_t ROP, mpz_t OP) + Set ROP to the truncated integer part of the square root of OP. + + - 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 the remainder OP-ROP1*ROP1, which + will be zero if OP is a perfect square. + + If ROP1 and ROP2 are the same variable, the results are undefined. + + - 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 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.