=================================================================== RCS file: /home/cvs/OpenXM_contrib/gmp/Attic/gmp.info-3,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-3 2000/12/01 05:44:46 1.1.1.3 +++ OpenXM_contrib/gmp/Attic/gmp.info-3 2003/08/25 16:06:02 1.1.1.4 @@ -1,1012 +1,1173 @@ -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. + +File: gmp.info, Node: Number Theoretic Functions, Next: Integer Comparisons, Prev: Integer Roots, Up: Integer Functions - Copyright (C) 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 -Free Software Foundation, Inc. +Number Theoretic Functions +========================== - 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. + - Function: int mpz_probab_prime_p (mpz_t N, int REPS) + Determine whether N is prime. Return 2 if N is definitely prime, + return 1 if N is probably prime (without being certain), or return + 0 if N is definitely composite. - 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. + This function does some trial divisions, then some Miller-Rabin + probabilistic primality tests. REPS controls how many such tests + are done, 5 to 10 is a reasonable number, more will reduce the + chances of a composite being returned as "probably prime". - 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. + Miller-Rabin and similar tests can be more properly called + compositeness tests. Numbers which fail are known to be composite + but those which pass might be prime or might be composite. Only a + few composites pass, hence those which pass are considered + probably prime. - -File: gmp.info, Node: Low-level Functions, Next: Random Number Functions, Prev: Floating-point Functions, Up: Top + - Function: void mpz_nextprime (mpz_t ROP, mpz_t OP) + Set ROP to the next prime greater than OP. -Low-level Functions -******************* + This function uses a probabilistic algorithm to identify primes. + For practical purposes it's adequate, the chance of a composite + passing will be extremely small. - This chapter describes low-level GMP functions, used to implement -the high-level GMP functions, but also intended for time-critical user -code. + - 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 one or both input operands are negative. - These functions start with the prefix `mpn_'. + - 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 `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. + 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. - 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. + - Function: void mpz_gcdext (mpz_t G, mpz_t S, mpz_t T, mpz_t A, mpz_t + B) + Set G to the greatest common divisor of A and B, and in addition + set S and T to coefficients satisfying A*S + B*T = G. G is always + positive, even if one or both of A and B are negative. - 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. + If T is `NULL' then that value is not computed. - A common requirement for all functions is that each source area -needs at least one limb. No size argument may be zero. Unless -otherwise stated, in-place operations are allowed where source and -destination are the same, but not where they only partly overlap. + - Function: void mpz_lcm (mpz_t ROP, mpz_t OP1, mpz_t OP2) + - Function: void mpz_lcm_ui (mpz_t ROP, mpz_t OP1, unsigned long OP2) + Set ROP to the least common multiple of OP1 and OP2. ROP is + always positive, irrespective of the signs of OP1 and OP2. ROP + will be zero if either OP1 or OP2 is zero. - The `mpn' functions are the base for the implementation of the -`mpz_', `mpf_', and `mpq_' functions. + - 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. + If the inverse exists, the return value is non-zero and ROP will + satisfy 0 <= ROP < OP2. If an inverse doesn't exist the return + value is zero and ROP is undefined. - This example adds the number beginning at S1P and the number -beginning at S2P and writes the sum at DESTP. All areas have SIZE -limbs. + - Function: int mpz_jacobi (mpz_t A, mpz_t B) + Calculate the Jacobi symbol (A/B). This is defined only for B odd. - cy = mpn_add_n (destp, s1p, s2p, size) + - Function: int mpz_legendre (mpz_t A, mpz_t P) + Calculate the Legendre symbol (A/P). This is defined only for P + an odd positive prime, and for such P it's identical to the Jacobi + symbol. -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, {s1p, s1size}. + - Function: int mpz_kronecker (mpz_t 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) + - Function: int mpz_si_kronecker (long A, mpz_t B) + - Function: int mpz_ui_kronecker (unsigned long A, mpz_t B) + Calculate the Jacobi symbol (A/B) with the Kronecker extension + (a/2)=(2/a) when a odd, or (a/2)=0 when a even. - - Function: mp_limb_t mpn_add_n (mp_limb_t *RP, const mp_limb_t *S1P, - const mp_limb_t *S2P, mp_size_t SIZE) - Add {S1P, SIZE} and {S2P, SIZE}, and write the SIZE least - significant limbs of the result to RP. Return carry, either 0 or - 1. + When B is odd the Jacobi symbol and Kronecker symbol are + identical, so `mpz_kronecker_ui' etc can be used for mixed + precision Jacobi symbols too. - 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., S1P - equals S2P, use `mpn_lshift' with a count of 1 for optimal speed. + For more information see Henri Cohen section 1.4.2 (*note + References::), or any number theory textbook. See also the + example program `demos/qcn.c' which uses `mpz_kronecker_ui'. - - Function: mp_limb_t mpn_add_1 (mp_limb_t *RP, const mp_limb_t *S1P, - mp_size_t SIZE, mp_limb_t S2LIMB) - Add {S1P, SIZE} and S2LIMB, and write the SIZE least significant - limbs of the result to RP. Return carry, either 0 or 1. + - 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. The return value is how many such occurrences were + removed. - - Function: mp_limb_t mpn_add (mp_limb_t *RP, const mp_limb_t *S1P, - mp_size_t S1SIZE, const mp_limb_t *S2P, mp_size_t S2SIZE) - Add {S1P, S1SIZE} and {S2P, S2SIZE}, and write the S1SIZE least - significant limbs of the result to RP. Return carry, either 0 or - 1. + - Function: void mpz_fac_ui (mpz_t ROP, unsigned long int OP) + Set ROP to OP!, the factorial of OP. - This function requires that S1SIZE is greater than or equal to - S2SIZE. + - 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. - - Function: mp_limb_t mpn_sub_n (mp_limb_t *RP, const mp_limb_t *S1P, - const mp_limb_t *S2P, mp_size_t SIZE) - Subtract {S2P, S2SIZE} from {S1P, SIZE}, and write the SIZE least - significant limbs of the result to RP. Return borrow, either 0 or - 1. + - Function: void mpz_fib_ui (mpz_t FN, unsigned long int N) + - Function: void mpz_fib2_ui (mpz_t FN, mpz_t FNSUB1, unsigned long + int N) + `mpz_fib_ui' sets FN to to F[n], the N'th Fibonacci number. + `mpz_fib2_ui' sets FN to F[n], and FNSUB1 to F[n-1]. - This is the lowest-level function for subtraction. It is the - preferred function for subtraction, since it is written in - assembly for most targets. + These functions are designed for calculating isolated Fibonacci + numbers. When a sequence of values is wanted it's best to start + with `mpz_fib2_ui' and iterate the defining F[n+1]=F[n]+F[n-1] or + similar. - - Function: mp_limb_t mpn_sub_1 (mp_limb_t *RP, const mp_limb_t *S1P, - mp_size_t SIZE, mp_limb_t S2LIMB) - Subtract S2LIMB from {S1P, SIZE}, and write the SIZE least - significant limbs of the result to RP. Return borrow, either 0 or - 1. + - Function: void mpz_lucnum_ui (mpz_t LN, unsigned long int N) + - Function: void mpz_lucnum2_ui (mpz_t LN, mpz_t LNSUB1, unsigned long + int N) + `mpz_lucnum_ui' sets LN to to L[n], the N'th Lucas number. + `mpz_lucnum2_ui' sets LN to L[n], and LNSUB1 to L[n-1]. - - Function: mp_limb_t mpn_sub (mp_limb_t *RP, const mp_limb_t *S1P, - mp_size_t S1SIZE, const mp_limb_t *S2P, mp_size_t S2SIZE) - Subtract {S2P, S2SIZE} from {S1P, S1SIZE}, and write the S1SIZE - least significant limbs of the result to RP. Return borrow, - either 0 or 1. + These functions are designed for calculating isolated Lucas + numbers. When a sequence of values is wanted it's best to start + with `mpz_lucnum2_ui' and iterate the defining L[n+1]=L[n]+L[n-1] + or similar. - This function requires that S1SIZE is greater than or equal to - S2SIZE. + The Fibonacci numbers and Lucas numbers are related sequences, so + it's never necessary to call both `mpz_fib2_ui' and + `mpz_lucnum2_ui'. The formulas for going from Fibonacci to Lucas + can be found in *Note Lucas Numbers Algorithm::, the reverse is + straightforward too. - - Function: void mpn_mul_n (mp_limb_t *RP, const mp_limb_t *S1P, const - mp_limb_t *S2P, mp_size_t SIZE) - Multiply {S1P, SIZE} and {S2P, SIZE}, and write the *entire* - result to RP. + +File: gmp.info, Node: Integer Comparisons, Next: Integer Logic and Bit Fiddling, Prev: Number Theoretic Functions, Up: Integer Functions - The destination has to have space for 2*SIZE limbs, even if the - significant result might be one limb smaller. +Comparison Functions +==================== - - Function: mp_limb_t mpn_mul_1 (mp_limb_t *RP, const mp_limb_t *S1P, - mp_size_t SIZE, mp_limb_t S2LIMB) - Multiply {S1P, SIZE} and S2LIMB, and write the SIZE least - significant limbs of the product to RP. Return the most - significant limb of the product. + - Function: int mpz_cmp (mpz_t OP1, mpz_t OP2) + - Function: int mpz_cmp_d (mpz_t OP1, double OP2) + - Macro: int mpz_cmp_si (mpz_t OP1, signed long int OP2) + - Macro: int mpz_cmp_ui (mpz_t OP1, unsigned long int OP2) + Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero + if OP1 = OP2, or a negative value if OP1 < OP2. - This is a low-level function that is a building block for general - multiplication as well as other operations in GMP. It is written - in assembly for most targets. + Note that `mpz_cmp_ui' and `mpz_cmp_si' are macros and will + evaluate their arguments more than once. - Don't call this function if S2LIMB is a power of 2; use - `mpn_lshift' with a count equal to the logarithm of S2LIMB - instead, for optimal speed. + - Function: int mpz_cmpabs (mpz_t OP1, mpz_t OP2) + - Function: int mpz_cmpabs_d (mpz_t OP1, double 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 abs(OP1) > abs(OP2), zero if abs(OP1) = abs(OP2), or a + negative value if abs(OP1) < abs(OP2). - - Function: mp_limb_t mpn_addmul_1 (mp_limb_t *RP, const mp_limb_t - *S1P, mp_size_t SIZE, mp_limb_t S2LIMB) - Multiply {S1P, SIZE} and S2LIMB, and add the SIZE least - significant limbs of the product to {RP, SIZE} and write the - result to RP. Return the most significant limb of the product, - plus carry-out from the addition. + Note that `mpz_cmpabs_si' is a macro and will evaluate its + arguments more than once. - This is a low-level function that is a building block for general - multiplication as well as other operations in GMP. It is written - in assembly for most targets. + - Macro: int mpz_sgn (mpz_t OP) + Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0. - - Function: mp_limb_t mpn_submul_1 (mp_limb_t *RP, const mp_limb_t - *S1P, mp_size_t SIZE, mp_limb_t S2LIMB) - Multiply {S1P, SIZE} and S2LIMB, and subtract the SIZE least - significant limbs of the product from {RP, SIZE} and write the - result to RP. Return the most significant limb of the product, - minus borrow-out from the subtraction. + This function is actually implemented as a macro. It evaluates + its argument multiple times. - This is a low-level function that is a building block for general - multiplication and division as well as other operations in GMP. - It is written in assembly for most targets. + +File: gmp.info, Node: Integer Logic and Bit Fiddling, Next: I/O of Integers, Prev: Integer Comparisons, Up: Integer Functions - - Function: mp_limb_t mpn_mul (mp_limb_t *RP, const mp_limb_t *S1P, - mp_size_t S1SIZE, const mp_limb_t *S2P, mp_size_t S2SIZE) - Multiply {S1P, S1SIZE} and {S2P, S2SIZE}, and write the result to - RP. Return the most significant limb of the result. +Logical and Bit Manipulation Functions +====================================== - The destination has to have space for S1SIZE + S2SIZE limbs, even - if the result might be one limb smaller. + These functions behave as if twos complement arithmetic were used +(although sign-magnitude is the actual implementation). The least +significant bit is number 0. - This function requires that S1SIZE is greater than or equal to - S2SIZE. The destination must be distinct from either input - operands. + - Function: void mpz_and (mpz_t ROP, mpz_t OP1, mpz_t OP2) + Set ROP to OP1 logical-and OP2. - - Function: void mpn_tdiv_qr (mp_limb_t *QP, mp_limb_t *RP, mp_size_t - QXN, const mp_limb_t *NP, mp_size_t NN, const mp_limb_t *DP, - mp_size_t DN) - Divide {NP, NN} by {DP, DN}. Write the quotient at QP and the - remainder at RP. + - Function: void mpz_ior (mpz_t ROP, mpz_t OP1, mpz_t OP2) + Set ROP to OP1 inclusive-or OP2. - The quotient written at QP will be NN - DN + 1 limbs. The - remainder written at RP will be DN limbs. + - Function: void mpz_xor (mpz_t ROP, mpz_t OP1, mpz_t OP2) + Set ROP to OP1 exclusive-or OP2. - It is required that NN is greater than or equal to DN. The QXN - operand must be zero. + - Function: void mpz_com (mpz_t ROP, mpz_t OP) + Set ROP to the one's complement of OP. - The quotient is rounded towards 0. + - Function: unsigned long int mpz_popcount (mpz_t OP) + If OP>=0, return the population count of OP, which is the number + of 1 bits in the binary representation. If OP<0, the number of 1s + is infinite, and the return value is MAX_ULONG, the largest + possible `unsigned long'. - No overlap between arguments is permitted. + - Function: unsigned long int mpz_hamdist (mpz_t OP1, mpz_t OP2) + If OP1 and OP2 are both >=0 or both <0, return the hamming + distance between the two operands, which is the number of bit + positions where OP1 and OP2 have different bit values. If one + operand is >=0 and the other <0 then the number of bits different + is infinite, and the return value is MAX_ULONG, the largest + possible `unsigned long'. - - Function: mp_limb_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) - [This function is obsolete. Please call `mpn_tdiv_qr' instead for - best performance.] + - Function: unsigned long int mpz_scan0 (mpz_t OP, unsigned long int + STARTING_BIT) + - Function: unsigned long int mpz_scan1 (mpz_t OP, unsigned long int + STARTING_BIT) + Scan OP, starting from bit STARTING_BIT, towards more significant + bits, until the first 0 or 1 bit (respectively) is found. Return + the index of the found bit. - 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; it will be - S3SIZE limbs long (i.e., as many limbs as the divisor). + If the bit at STARTING_BIT is already what's sought, then + STARTING_BIT is returned. - In addition to an integer quotient, XSIZE fraction limbs are - developed, and stored after the integral limbs. For most usages, - XSIZE will be zero. + If there's no bit found, then MAX_ULONG is returned. This will + happen in `mpz_scan0' past the end of a positive number, or + `mpz_scan1' past the end of a negative. - 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. + - Function: void mpz_setbit (mpz_t ROP, unsigned long int BIT_INDEX) + Set bit BIT_INDEX in ROP. - If the quotient is not needed, pass RS2P + S3SIZE as R1P. Aside - from that special case, no overlap between arguments is permitted. + - Function: void mpz_clrbit (mpz_t ROP, unsigned long int BIT_INDEX) + Clear bit BIT_INDEX in ROP. - Return the most significant limb of the quotient, either 0 or 1. + - Function: int mpz_tstbit (mpz_t OP, unsigned long int BIT_INDEX) + Test bit BIT_INDEX in OP and return 0 or 1 accordingly. - The area at R1P needs to be RS2SIZE - S3SIZE + XSIZE limbs large. + +File: gmp.info, Node: I/O of Integers, Next: Integer Random Numbers, Prev: Integer Logic and Bit Fiddling, Up: Integer Functions - - 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) - - Macro: mp_limb_t mpn_divmod_1 (mp_limb_t *R1P, 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. +Input and Output Functions +========================== - The integer quotient is written to {R1P+XSIZE, S2SIZE} and in - addition XSIZE fraction limbs are developed and written to {R1P, - XSIZE}. Either or both S2SIZE and XSIZE can be zero. For most - usages, XSIZE will be zero. + 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. - `mpn_divmod_1' exists for upward source compatibility and is - simply a macro calling `mpn_divrem_1' with an XSIZE of 0. + 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. - The areas at R1P and S2P have to be identical or completely - separate, not partially overlapping. + - 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. - - Function: mp_limb_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.* + Return the number of bytes written, or if an error occurred, + return 0. - - Macro: mp_limb_t mpn_divexact_by3 (mp_limb_t *RP, mp_limb_t *SP, - mp_size_t SIZE) - - Function: mp_limb_t mpn_divexact_by3c (mp_limb_t *RP, mp_limb_t *SP, - mp_size_t SIZE, mp_limb_t CARRY) - Divide {SP, SIZE} by 3, expecting it to divide exactly, and - writing the result to {RP, SIZE}. If 3 divides exactly, the - return value is zero and the result is the quotient. If not, the - return value is non-zero and the result won't be anything useful. + - 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. - `mpn_divexact_by3c' takes an initial carry parameter, which can be - the return value from a previous call, so a large calculation can - be done piece by piece. `mpn_divexact_by3' is simply a macro - calling `mpn_divexact_by3c' with a 0 carry parameter. + Return the number of bytes read, or if an error occurred, return 0. - These routines use a multiply-by-inverse and will be faster than - `mpn_divrem_1' on CPUs with fast multiplication but slow division. + - 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). - The source a, result q, size n, initial carry i, and return value - c satisfy c*b^n + a-i = 3*q, where b is the size of a limb (2^32 - or 2^64). c is always 0, 1 or 2, and the initial carry must also - be 0, 1 or 2 (these are both borrows really). When c=0, clearly - q=(a-i)/3. When c!=0, the remainder (a-i) mod 3 is given by 3-c, - because b == 1 mod 3. + The output can be read with `mpz_inp_raw'. - - 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. S1SIZE - can be zero. + Return the number of bytes written, or if an error occurred, + return 0. - - 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.* + 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. - - Function: mp_limb_t mpn_bdivmod (mp_limb_t *RP, 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 RP, and returns the high D mod - BITS_PER_MP_LIMB bits of Q. + - 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. - {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 RP <= S1P. + 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. - This function requires that S1SIZE * BITS_PER_MP_LIMB >= D, and - that {S2P, S2SIZE} is odd. + +File: gmp.info, Node: Integer Random Numbers, Next: Integer Import and Export, Prev: I/O of Integers, Up: Integer Functions - *This interface is preliminary. It might change incompatibly in - future revisions.* +Random Number Functions +======================= - - Function: mp_limb_t mpn_lshift (mp_limb_t *RP, 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 RP. COUNT might - be in the range 1 to n - 1, on an n-bit machine. The bits shifted - out to the left are returned. + 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. - Overlapping of the destination space and the source space is - allowed in this function, provided RP >= SRC_PTR. + - 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. - This function is written in assembly for most targets. + The variable STATE must be initialized by calling one of the + `gmp_randinit' functions (*Note Random State Initialization::) + before invoking this function. - - Function: mp_limp_t mpn_rshift (mp_limb_t *RP, 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 RP. COUNT might - be in the range 1 to n - 1, on an n-bit machine. The bits shifted - out to the right are returned. + - 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. - Overlapping of the destination space and the source space is - allowed in this function, provided RP <= SRC_PTR. + The variable STATE must be initialized by calling one of the + `gmp_randinit' functions (*Note Random State Initialization::) + before invoking this function. - This function is written in assembly for most targets. + - 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. - - Function: int mpn_cmp (const mp_limb_t *S1P, const mp_limb_t *S2P, - mp_size_t SIZE) - Compare {S1P, SIZE} and {S2P, SIZE} and return a positive value if - s1 > src2, 0 of they are equal, and a negative value if s1 < src2. + The variable STATE must be initialized by calling one of the + `gmp_randinit' functions (*Note Random State Initialization::) + before invoking this function. - - Function: mp_size_t mpn_gcd (mp_limb_t *RP, mp_limb_t *S1P, - mp_size_t S1SIZE, mp_limb_t *S2P, mp_size_t S2SIZE) - Puts at RP the greatest common divisor of {S1P, S1SIZE} and {S2P, - S2SIZE}; both source operands are destroyed by the operation. The - size in limbs of the greatest common divisor is returned. + - 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. - {S1P, S1SIZE} must have at least as many bits as {S2P, S2SIZE}, - and {S2P, S2SIZE} must be odd. + This function is obsolete. Use `mpz_urandomb' or `mpz_urandomm' + instead. - - Function: mp_limb_t mpn_gcd_1 (const mp_limb_t *S1P, mp_size_t - S1SIZE, mp_limb_t S2LIMB) - Return the greatest common divisor of {S1P, S1SIZE} and S2LIMB, - where S2LIMB (as well as S1SIZE) must be different from 0. + - 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. - - Function: mp_size_t mpn_gcdext (mp_limb_t *R1P, mp_limb_t *R2P, - mp_size_t *R2SIZE, mp_limb_t *S1P, mp_size_t S1SIZE, - mp_limb_t *S2P, mp_size_t S2SIZE) - Compute the greatest common divisor of {S1P, S1SIZE} and {S2P, - S2SIZE}. Store the gcd at R1P and return its size in limbs. - Write the first cofactor at R2P and store its size in *R2SIZE. If - the cofactor is negative, *R2SIZE is negative and R2P is the - absolute value of the cofactor. + This function is obsolete. Use `mpz_rrandomb' instead. - {S1P, S1SIZE} must be greater than or equal to {S2P, S2SIZE}. - Neither operand may equal 0. Both source operands are destroyed, - plus one limb past the end of each, ie. {S1P, S1SIZE+1} and {S2P, - S2SIZE+1}. + +File: gmp.info, Node: Integer Import and Export, Next: Miscellaneous Integer Functions, Prev: Integer Random Numbers, Up: Integer Functions - - 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'. +Integer Import and Export +========================= - 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. + `mpz_t' variables can be converted to and from arbitrary words of +binary data with the following functions. - 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. + - Function: void mpz_import (mpz_t ROP, size_t COUNT, int ORDER, int + SIZE, int ENDIAN, size_t NAILS, const void *OP) + Set ROP from an array of word data at OP. - The area at R1P needs to have space for ceil(SIZE/2) limbs. The - area at R2P needs to be SIZE limbs large. + The parameters specify the format of the data. COUNT many words + are read, each SIZE bytes. ORDER can be 1 for most significant + word first or -1 for least significant first. Within each word + ENDIAN can be 1 for most significant byte first, -1 for least + significant first, or 0 for the native endianness of the host CPU. + The most significant NAILS bits of each word are skipped, this + can be 0 to use the full words. - - 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. + There are no data alignment restrictions on OP, any address is + allowed. - The area at S1P is clobbered. + Here's an example converting an array of `unsigned long' data, most + significant element first and host byte order within each value. - Return the number of characters in STR. + unsigned long a[20]; + mpz_t z; + mpz_import (z, 20, 1, sizeof(a[0]), 0, 0, a); - The area at STR has to have space for the largest possible number - represented by a S1SIZE long limb array, plus one extra character. + This example assumes the full `sizeof' bytes are used for data in + the given type, which is usually true, and certainly true for + `unsigned long' everywhere we know of. However on Cray vector + systems it may be noted that `short' and `int' are always stored + in 8 bytes (and with `sizeof' indicating that) but use only 32 or + 46 bits. The NAILS feature can account for this, by passing for + instance `8*sizeof(int)-INT_BIT'. - - Function: 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. + - Function: void *mpz_export (void *ROP, size_t *COUNT, int ORDER, int + SIZE, int ENDIAN, size_t NAILS, mpz_t OP) + Fill ROP with word data from OP. - Return the number of limbs stored in R1P. + The parameters specify the format of the data produced. Each word + will be SIZE bytes and ORDER can be 1 for most significant word + first or -1 for least significant first. Within each word ENDIAN + can be 1 for most significant byte first, -1 for least significant + first, or 0 for the native endianness of the host CPU. The most + significant NAILS bits of each word are unused and set to zero, + this can be 0 to produce full words. - - 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. + The number of words produced is written to `*COUNT'. ROP must + have enough space for the data, or if ROP is `NULL' then a result + array of the necessary size is allocated using the current GMP + allocation function (*note Custom Allocation::). In either case + the return value is the destination used, ROP or the allocated + block. - 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. + If OP is non-zero then the most significant word produced will be + non-zero. If OP is zero then the count returned will be zero and + nothing written to ROP. If ROP is `NULL' in this case, no block + is allocated, just `NULL' is returned. - - 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. + There are no data alignment restrictions on ROP, any address is + allowed. The sign of OP is ignored, just the absolute value is + used. - 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. + When an application is allocating space itself the required size + can be determined with a calculation like the following. Since + `mpz_sizeinbase' always returns at least 1, `count' here will be + at least one, which avoids any portability problems with + `malloc(0)', though if `z' is zero no space at all is actually + needed. - - Function: void mpn_random (mp_limb_t *R1P, mp_size_t R1SIZE) - - Function: void mpn_random2 (mp_limb_t *R1P, mp_size_t R1SIZE) - Generate a random number of length R1SIZE and store it at R1P. - The most significant limb is always non-zero. `mpn_random' - generates uniformly distributed limb data, `mpn_random2' generates - long strings of zeros and ones in the binary representation. + numb = 8*size - nail; + count = (mpz_sizeinbase (z, 2) + numb-1) / numb; + p = malloc (count * size); - `mpn_random2' is intended for testing the correctness of the `mpn' - routines. + +File: gmp.info, Node: Miscellaneous Integer Functions, Prev: Integer Import and Export, Up: Integer Functions - - Function: unsigned long int mpn_popcount (const mp_limb_t *S1P, - unsigned long int SIZE) - Count the number of set bits in {S1P, SIZE}. +Miscellaneous Functions +======================= - - 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}. + - 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. - - 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. + - 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 argument + more than once. - -File: gmp.info, Node: Random Number Functions, Next: BSD Compatible Functions, Prev: Low-level Functions, Up: Top + - 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. -Random Number Functions -*********************** + - 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 sign of OP is ignored, just + the absolute value is used. The result will be exact or 1 too + big. If BASE is a power of 2, the result will always be exact. + If OP is zero the return value is always 1. - There are two groups of random number functions in GNU MP; older -functions that call C library random number generators, rely on a global -state, and aren't very random; and newer functions that don't have these -problems. The newer functions are self-contained, they accept a random -state parameter that supplants global state, and generate good random -numbers. + 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 + null-terminator). - The random state parameter is of the type `gmp_randstate_t'. It -must be initialized by a call to one of the `gmp_randinit' functions -(*Note Random State Initialization::). The initial seed is set using -one of the `gmp_randseed' functions (*Note Random State -Initialization::). + +File: gmp.info, Node: Rational Number Functions, Next: Floating-point Functions, Prev: Integer Functions, Up: Top - The size of the seed determines the number of different sequences of -random numbers that is possible to generate. The "quality" of the seed -is the randomness of a given seed compared to the previous seed used -and affects the randomness of separate number sequences. +Rational Number Functions +************************* - The algorithm for assigning seed is critical if the generated random -numbers are to be used for important applications, such as generating -cryptographic keys. + This chapter describes the GMP functions for performing arithmetic +on rational numbers. These functions start with the prefix `mpq_'. - The traditional method is to use the current system time for -seeding. One has to be careful when using the current time though. If -the application seeds the random functions very often, say several -times per second, and the resolution of the system clock is -comparatively low, like one second, the same sequence of numbers will -be generated until the system clock ticks. Furthermore, the current -system time is quite easy to guess, so a system depending on any -unpredictability of the random number sequence should absolutely not -use that as its only source for a seed value. + Rational numbers are stored in objects of type `mpq_t'. - On some systems there is a special device, often called -`/dev/random', which provides a source of somewhat random numbers more -usable as seed. + 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. - The functions actually generating random functions are documented -under "Miscellaneous Functions" in their respective function class: -*Note Miscellaneous Integer Functions::, *Note Miscellaneous Float -Functions::. + 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. + - 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. + * Menu: -* Random State Initialization:: How to initialize a random state. +* Initializing Rationals:: +* Rational Conversions:: +* Rational Arithmetic:: +* Comparing Rationals:: +* Applying Integer Functions:: +* I/O of Rationals::  -File: gmp.info, Node: Random State Initialization, Prev: Random Number Functions, Up: Random Number Functions +File: gmp.info, Node: Initializing Rationals, Next: Rational Conversions, Prev: Rational Number Functions, Up: Rational Number Functions -Random State Initialization -=========================== +Initialization and Assignment Functions +======================================= - See *Note Random Number Functions:: for a discussion on how to -choose the initial seed value passed to these functions. + - 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. - - Function: void gmp_randinit (gmp_randstate_t STATE, gmp_randalg_t - ALG, ...) - Initialize random state variable STATE. + - 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. - ALG denotes what algorithm to use for random number generation. - Use one of - - GMP_RAND_ALG_LC -- Linear congruential. + - 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. - A fast generator defined by X = (aX + c) mod m. + - 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. - A third argument SIZE of type unsigned long int is required. - SIZE is the size of the largest good quality random number to - be generated, expressed in number of bits. If the random - generation functions are asked for a bigger random number - than indicated by this parameter, two or more numbers of SIZE - bits will be generated and concatenated, resulting in a "bad" - random number. This can be used to generate big random - numbers relatively cheap if the quality of randomness isn't - of great importance. + - Function: int mpq_set_str (mpq_t ROP, char *STR, int BASE) + Set ROP from a null-terminated string STR in the given BASE. - a, c, and m are picked from a table where the modulus (m) is - a power of 2 and the multiplier is congruent to 5 (mod 8). - The choice is based on the SIZE parameter. The maximum SIZE - supported by this algorithm is 128. If you need bigger - random numbers, use your own scheme and call one of the other - `gmp_randinit' functions. + The string can be an integer like "41" or a fraction like + "41/152". The fraction must be in canonical form (*note Rational + Number Functions::), or if not then `mpq_canonicalize' must be + called. + The numerator and optional denominator are parsed the same as in + `mpz_set_str' (*note Assigning Integers::). White space is + allowed in the string, and is simply ignored. The BASE can vary + from 2 to 36, or if BASE is 0 then the leading characters are + used: `0x' for hex, `0' for octal, or decimal otherwise. Note + that this is done separately for the numerator and denominator, so + for instance `0xEF/100' is 239/100, whereas `0xEF/0x100' is + 239/256. - If ALG is 0 or GMP_RAND_ALG_DEFAULT, the default algorithm is - used. The default algorithm is typically a fast algorithm like - the linear congruential and requires a third SIZE argument (see - GMP_RAND_ALG_LC). + The return value is 0 if the entire string is a valid number, or + -1 if not. - When you're done with a STATE variable, call `gmp_randclear' to - deallocate any memory allocated by this function. + - Function: void mpq_swap (mpq_t ROP1, mpq_t ROP2) + Swap the values ROP1 and ROP2 efficiently. - `gmp_randinit' may set the following bits in GMP_ERRNO: - * GMP_ERROR_UNSUPPORTED_ARGUMENT -- ALG is unsupported + +File: gmp.info, Node: Rational Conversions, Next: Rational Arithmetic, Prev: Initializing Rationals, Up: Rational Number Functions - * GMP_ERROR_INVALID_ARGUMENT -- SIZE is too big +Conversion Functions +==================== - - Function: void gmp_randinit_lc_2exp (gmp_randstate_t STATE, mpz_t A, - unsigned long int C, unsigned long int M2EXP) + - Function: double mpq_get_d (mpq_t OP) + Convert OP to a `double'. - Initialize random state variable STATE with given linear - congruential scheme. + - Function: void mpq_set_d (mpq_t ROP, double OP) + - Function: void mpq_set_f (mpq_t ROP, mpf_t OP) + Set ROP to the value of OP, without rounding. - Parameters A, C, and M2EXP are the multiplier, adder, and modulus - for the linear congruential scheme to use, respectively. The - modulus is expressed as a power of 2, so that M = 2^M2EXP. + - Function: char * mpq_get_str (char *STR, int BASE, mpq_t OP) + Convert OP to a string of digits in base BASE. The base may vary + from 2 to 36. The string will be of the form `num/den', or if the + denominator is 1 then just `num'. - The least significant bits of a random number generated by the - linear congruential algorithm where the modulus is a power of two - are not very random. Therefore, the lower half of a random number - generated by an LC scheme initialized with this function is - discarded. Thus, the size of a random number is M2EXP / 2 - (rounded upwards) bits when this function has been used for - initializing the random state. + 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. - When you're done with a STATE variable, call `gmp_randclear' to - deallocate any memory allocated by this function. + If STR is not `NULL', it should point to a block of storage large + enough for the result, that being - - Function: void gmp_randseed (gmp_randstate_t STATE, mpz_t SEED) - - Function: void gmp_randseed_ui (gmp_randstate_t STATE, unsigned long - int SEED) - Set the initial seed value. + mpz_sizeinbase (mpq_numref(OP), BASE) + + mpz_sizeinbase (mpq_denref(OP), BASE) + 3 - Parameter SEED is the initial random seed. The function - `gmp_randseed_ui' takes the SEED as an unsigned long int rather - than as an mpz_t. + The three extra bytes are for a possible minus sign, possible + slash, and the null-terminator. - - Function: void gmp_randclear (gmp_randstate_t STATE) - Free all memory occupied by STATE. Make sure to call this - function for all `gmp_randstate_t' variables when you are done with - them. + A pointer to the result string is returned, being either the + allocated block, or the given STR.  -File: gmp.info, Node: BSD Compatible Functions, Next: Custom Allocation, Prev: Random Number Functions, Up: Top +File: gmp.info, Node: Rational Arithmetic, Next: Comparing Rationals, Prev: Rational Conversions, Up: Rational Number Functions -Berkeley MP Compatible Functions -******************************** +Arithmetic Functions +==================== - These functions are intended to be fully compatible with the -Berkeley MP library which is available on many BSD derived U*ix -systems. The `--enable-mpbsd' option must be used when building GNU MP -to make these available (*note Installing GMP::). + - Function: void mpq_add (mpq_t SUM, mpq_t ADDEND1, mpq_t ADDEND2) + Set SUM to ADDEND1 + ADDEND2. - 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. + - Function: void mpq_sub (mpq_t DIFFERENCE, mpq_t MINUEND, mpq_t + SUBTRAHEND) + Set DIFFERENCE to MINUEND - SUBTRAHEND. - 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'. + - Function: void mpq_mul (mpq_t PRODUCT, mpq_t MULTIPLIER, mpq_t + MULTIPLICAND) + Set PRODUCT to MULTIPLIER times MULTIPLICAND. - 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 your -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'. + - Function: void mpq_mul_2exp (mpq_t ROP, mpq_t OP1, unsigned long int + OP2) + Set ROP to OP1 times 2 raised to OP2. - - 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 mpq_div (mpq_t QUOTIENT, mpq_t DIVIDEND, mpq_t + DIVISOR) + Set QUOTIENT to DIVIDEND/DIVISOR. - - 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: void mpq_div_2exp (mpq_t ROP, mpq_t OP1, unsigned long int + OP2) + Set ROP to OP1 divided by 2 raised to OP2. - - Function: void move (MINT *SRC, MINT *DEST) - Set DEST to SRC by copying. Both variables must be previously - initialized. + - Function: void mpq_neg (mpq_t NEGATED_OPERAND, mpq_t OPERAND) + Set NEGATED_OPERAND to -OPERAND. - - Function: void madd (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION) - Add SRC_1 and SRC_2 and put the sum in DESTINATION. + - Function: void mpq_abs (mpq_t ROP, mpq_t OP) + Set ROP to the absolute value of OP. - - Function: void msub (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION) - Subtract SRC_2 from SRC_1 and put the difference in DESTINATION. + - 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. - - Function: void mult (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION) - Multiply SRC_1 and SRC_2 and put the product in DESTINATION. + +File: gmp.info, Node: Comparing Rationals, Next: Applying Integer Functions, Prev: Rational Arithmetic, Up: Rational Number Functions - - 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. +Comparison Functions +==================== - Some implementations of these functions work differently--or not - at all--for negative arguments. + - 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. - - 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). + To determine if two rationals are equal, `mpq_equal' is faster than + `mpq_cmp'. - If ROOT and REMAINDER are the same variable, the results are - undefined. + - Macro: int mpq_cmp_ui (mpq_t OP1, unsigned long int NUM2, unsigned + long int DEN2) + - Macro: int mpq_cmp_si (mpq_t OP1, 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. - - Function: void pow (MINT *BASE, MINT *EXP, MINT *MOD, MINT *DEST) - Set DEST to (BASE raised to EXP) modulo MOD. + NUM2 and DEN2 are allowed to have common factors. - - Function: void rpow (MINT *BASE, signed short int EXP, MINT *DEST) - Set DEST to BASE raised to EXP. + These functions are implemented as a macros and evaluate their + arguments multiple times. - - Function: void gcd (MINT *OPERAND1, MINT *OPERAND2, MINT *RES) - Set RES to the greatest common divisor of OPERAND1 and OPERAND2. + - Macro: int mpq_sgn (mpq_t OP) + Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0. - - 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. + This function is actually implemented as a macro. It evaluates its + arguments multiple times. - - 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. + - 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. - - Function: void mout (MINT *SRC) - Output SRC to `stdout', as a decimal string. Also output a - newline. + +File: gmp.info, Node: Applying Integer Functions, Next: I/O of Rationals, Prev: Comparing Rationals, Up: Rational Number Functions - - 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. +Applying Integer Functions to Rationals +======================================= - - 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'.* + The set of `mpq' functions is quite small. In particular, there are +few functions for either input or output. The following functions give +direct access to the numerator and denominator of an `mpq_t'. + Note that if an assignment to the numerator and/or denominator could +take an `mpq_t' out of the canonical form described at the start of +this chapter (*note Rational Number Functions::) then +`mpq_canonicalize' must be called before any other `mpq' functions are +applied to that `mpq_t'. + + - 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. + + - Function: void mpq_get_num (mpz_t NUMERATOR, mpq_t RATIONAL) + - Function: void mpq_get_den (mpz_t DENOMINATOR, mpq_t RATIONAL) + - Function: void mpq_set_num (mpq_t RATIONAL, mpz_t NUMERATOR) + - Function: void mpq_set_den (mpq_t RATIONAL, mpz_t DENOMINATOR) + Get or set the numerator or denominator of a rational. These + functions are equivalent to calling `mpz_set' with an appropriate + `mpq_numref' or `mpq_denref'. Direct use of `mpq_numref' or + `mpq_denref' is recommended instead of these functions. +  -File: gmp.info, Node: Custom Allocation, Next: Contributors, Prev: BSD Compatible Functions, Up: Top +File: gmp.info, Node: I/O of Rationals, Prev: Applying Integer Functions, Up: Rational Number Functions -Custom Allocation -***************** +Input and Output Functions +========================== - By default, GMP uses `malloc', `realloc' and `free' for memory -allocation. If `malloc' or `realloc' fails, GMP prints a message to -the standard error output and terminates execution. + When using any of these functions, it's a good idea to include +`stdio.h' before `gmp.h', since that will allow `gmp.h' to define +prototypes for these functions. - Some applications might want to allocate memory in other ways, or -might not want a fatal error when there is no more memory available. -To accomplish this, you can specify alternative memory allocation -functions. + Passing a `NULL' pointer for a STREAM argument to any of these +functions will make them read from `stdin' and write to `stdout', +respectively. - This can be done in the Berkeley compatibility library as well as -the main GMP library. + - 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'. - - 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. + Return the number of bytes written, or if an error occurred, + return 0. - *Be sure to call this function only when there are no active GMP - objects allocated using the previous memory functions! Usually, - that means that you have to call this function before any other - GMP function.* + - Function: size_t mpq_inp_str (mpq_t ROP, FILE *STREAM, int BASE) + Read a string of digits from STREAM and convert them to a rational + in ROP. Any initial white-space characters are read and + discarded. Return the number of characters read (including white + space), or 0 if a rational could not be read. - The functions you supply should fit the following declarations: + The input can be a fraction like `17/63' or just an integer like + `123'. Reading stops at the first character not in this form, and + white space is not permitted within the string. If the input + might not be in canonical form, then `mpq_canonicalize' must be + called (*note Rational Number Functions::). - - 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. + The BASE can be between 2 and 36, or can be 0 in which case the + leading characters of the string determine the base, `0x' or `0X' + for hexadecimal, `0' for octal, or decimal otherwise. The leading + characters are examined separately for the numerator and + denominator of a fraction, so for instance `0x10/11' is 16/11, + whereas `0x10/0x11' is 16/17. - - 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. + +File: gmp.info, Node: Floating-point Functions, Next: Low-level Functions, Prev: Rational Number Functions, Up: Top - 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. +Floating-point Functions +************************ - - Function: void deallocate_function (void *PTR, size_t SIZE) - De-allocate the space pointed to by PTR. + GMP floating point numbers are stored in objects of type `mpf_t' and +functions operating on them have an `mpf_' prefix. - You can assume that the space at PTR was formerly returned from - `allocate_function' or `reallocate_function', for a request for - SIZE storage units. + The mantissa of each float has a user-selectable precision, limited +only by available memory. Each variable has its own precision, and +that can be increased or decreased at any time. - (A "storage unit" is the unit in which the `sizeof' operator returns -the size of an object, normally an 8 bit byte.) + The exponent of each float is a fixed precision, one machine word on +most systems. In the current implementation the exponent is a count of +limbs, so for example on a 32-bit system this means a range of roughly +2^-68719476768 to 2^68719476736, or on a 64-bit system this will be +greater. Note however `mpf_get_str' can only return an exponent which +fits an `mp_exp_t' and currently `mpf_set_str' doesn't accept exponents +bigger than a `long'. + Each variable keeps a size for the mantissa data actually in use. +This means that if a float is exactly represented in only a few bits +then only those bits will be used in a calculation, even if the +selected precision is high. + + All calculations are performed to the precision of the destination +variable. Each function is defined to calculate with "infinite +precision" followed by a truncation to the destination precision, but +of course the work done is only what's needed to determine a result +under that definition. + + The precision selected for a variable is a minimum value, GMP may +increase it a little to facilitate efficient calculation. Currently +this means rounding up to a whole limb, and then sometimes having a +further partial limb, depending on the high limb of the mantissa. But +applications shouldn't be concerned by such details. + + The mantissa in stored in binary, as might be imagined from the fact +precisions are expressed in bits. One consequence of this is that +decimal fractions like 0.1 cannot be represented exactly. The same is +true of plain IEEE `double' floats. This makes both highly unsuitable +for calculations involving money or other values that should be exact +decimal fractions. (Suitably scaled integers, or perhaps rationals, +are better choices.) + + `mpf' functions and variables have no special notion of infinity or +not-a-number, and applications must take care not to overflow the +exponent or results will be unpredictable. This might change in a +future release. + + Note that the `mpf' functions are _not_ intended as a smooth +extension to IEEE P754 arithmetic. In particular results obtained on +one computer often differ from the results on a computer with a +different word size. + +* Menu: + +* Initializing Floats:: +* Assigning Floats:: +* Simultaneous Float Init & Assign:: +* Converting Floats:: +* Float Arithmetic:: +* Float Comparison:: +* I/O of Floats:: +* Miscellaneous Float Functions:: +  -File: gmp.info, Node: Contributors, Next: References, Prev: Custom Allocation, Up: Top +File: gmp.info, Node: Initializing Floats, Next: Assigning Floats, Prev: Floating-point Functions, Up: Floating-point Functions -Contributors -************ +Initialization Functions +======================== - Torbjorn Granlund wrote the original GMP library and is still -developing and maintaining it. Several other individuals and -organizations have contributed to GMP in various ways. Here is a list -in chronological order: + - 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. - Gunnar Sjoedin and Hans Riesel helped with mathematical problems in -early versions of the library. + - Function: unsigned long int mpf_get_default_prec (void) + Return the default default precision actually used. - Richard Stallman contributed to the interface design and revised the -first version of this manual. + 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. - Brian Beuning and Doug Lea helped with testing of early versions of -the library and made creative suggestions. + - 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'. - John Amanatides of York University in Canada contributed the function -`mpz_probab_prime_p'. + - 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. - Paul Zimmermann of Inria sparked the development of GMP 2, with his -comparisons between bignum packages. + - 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. - 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. + 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); + } - Per Bothner of Cygnus Support helped to set up GMP to use Cygnus' -configure. He has also made valuable suggestions and tested numerous -intermediary releases. + 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. - Joachim Hollman was involved in the design of the `mpf' interface, -and in the `mpz' design revisions for version 2. + - Function: unsigned long int mpf_get_prec (mpf_t OP) + Return the current precision of OP, in bits. - Bennet Yee contributed the functions `mpz_jacobi' and `mpz_legendre'. + - Function: void mpf_set_prec (mpf_t ROP, unsigned long int PREC) + Set the precision of ROP to be *at least* PREC bits. The value in + ROP will be truncated to the new precision. - Andreas Schwab contributed the files `mpn/m68k/lshift.S' and -`mpn/m68k/rshift.S'. + This function requires a call to `realloc', and so should not be + used in a tight loop. - The development of floating point functions of GNU MP 2, were -supported in part by the ESPRIT-BRA (Basic Research Activities) 6846 -project POSSO (POlynomial System SOlving). + - Function: void mpf_set_prec_raw (mpf_t ROP, unsigned long int PREC) + Set the precision of ROP to be *at least* PREC bits, without + changing the memory allocated. - GNU MP 2 was finished and released by SWOX AB (formerly known as TMG -Datakonsult), Swedenborgsgatan 23, SE-118 27 STOCKHOLM, SWEDEN, in -cooperation with the IDA Center for Computing Sciences, USA. + PREC must be no more than the allocated precision for ROP, that + being the precision when ROP was initialized, or in the most recent + `mpf_set_prec'. - Robert Harley of Inria, France and David Seal of ARM, England, -suggested clever improvements for population count. + The value in ROP is unchanged, and in particular if it had a higher + precision than PREC it will retain that higher precision. New + values written to ROP will use the new PREC. - Robert Harley also wrote highly optimized Karatsuba and 3-way Toom -multiplication functions for GMP 3. He also contributed the ARM -assembly code. + Before calling `mpf_clear' or the full `mpf_set_prec', another + `mpf_set_prec_raw' call must be made to restore ROP to its original + allocated precision. Failing to do so will have unpredictable + results. - Torsten Ekedahl of the Mathematical department of Stockholm -University provided significant inspiration during several phases of -the GMP development. His mathematical expertise helped improve several -algorithms. + `mpf_get_prec' can be used before `mpf_set_prec_raw' to get the + original allocated precision. After `mpf_set_prec_raw' it + reflects the PREC value set. - Paul Zimmermann wrote the Burnikel-Ziegler division code, the REDC -code, the REDC-based mpz_powm code, and the FFT multiply code. The -ECMNET project Paul is organizing has been a driving force behind many -of the optimization of GMP 3. + `mpf_set_prec_raw' is an efficient way to use an `mpf_t' variable + at different precisions during a calculation, perhaps to gradually + increase precision in an iteration, or just to use various + different precisions for different purposes during a calculation. - Linus Nordberg wrote the new configure system based on autoconf and -implemented the new random functions. + +File: gmp.info, Node: Assigning Floats, Next: Simultaneous Float Init & Assign, Prev: Initializing Floats, Up: Floating-point Functions - Kent Boortz made the Macintosh port. +Assignment Functions +==================== - Kevin Ryde wrote a lot of very high quality x86 code, optimized for -most CPU variants. He also made countless other valuable contributions. + These functions assign new values to already initialized floats +(*note Initializing Floats::). - Steve Root helped write the optimized alpha 21264 assembly code. + - 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. - GNU MP 3.1 was finished and released by Torbjorn Granlund and Kevin -Ryde. Torbjorn's work was partially funded by the IDA Center for -Computing Sciences, USA. + - 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. The decimal + point expected is taken from the current locale, on systems + providing `localeconv'. - (This list is chronological, not ordered after significance. If you -have contributed to GMP but are not listed above, please tell - about the omission!) + 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. + 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. + + 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 + 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?] + + This function returns 0 if the entire string is a valid number in + base BASE. Otherwise it returns -1. + + - Function: void mpf_swap (mpf_t ROP1, mpf_t ROP2) + Swap ROP1 and ROP2 efficiently. Both the values and the + precisions of the two variables are swapped. +  -File: gmp.info, Node: References, Next: Concept Index, Prev: Contributors, Up: Top +File: gmp.info, Node: Simultaneous Float Init & Assign, Next: Converting Floats, Prev: Assigning Floats, Up: Floating-point Functions -References -********** +Combined Initialization and Assignment Functions +================================================ - * Donald E. Knuth, "The Art of Computer Programming", vol 2, - "Seminumerical Algorithms", 3rd edition, Addison-Wesley, 1988. + 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...' - * John D. Lipson, "Elements of Algebra and Algebraic Computing", The - Benjamin Cummings Publishing Company Inc, 1981. + 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! - * Richard M. Stallman, "Using and Porting GCC", Free Software - Foundation, 1999, available online - `http://www.gnu.org/software/gcc/onlinedocs/', and in the GCC - package `ftp://ftp.gnu.org/pub/gnu/gcc/'. + - 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. - * Peter L. Montgomery, "Modular Multiplication Without Trial - Division", in Mathematics of Computation, volume 44, number 170, - April 1985. + The precision of ROP will be taken from the active default + precision, as set by `mpf_set_default_prec'. - * Torbjorn Granlund and Peter L. Montgomery, "Division by Invariant - Integers using Multiplication", in Proceedings of the SIGPLAN - PLDI'94 Conference, June 1994. Available online, - `ftp://ftp.cwi.nl/pub/pmontgom/divcnst.psa4.gz' (and .psl.gz too). + - 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. - * Tudor Jebelean, "An algorithm for exact division", Journal of - Symbolic Computation, v. 15, 1993, pp. 169-180. Research report - version available online - `ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1992/92-35.ps.gz' + Note that ROP is initialized even if an error occurs. (I.e., you + have to call `mpf_clear' for it.) - * Kenneth Weber, "The accelerated integer GCD algorithm", ACM - Transactions on Mathematical Software, v. 21 (March), 1995, pp. - 111-122. + The precision of ROP will be taken from the active default + precision, as set by `mpf_set_default_prec'. - * Christoph Burnikel and Joachim Ziegler, "Fast Recursive Division", - Max-Planck-Institut fuer Informatik Research Report - MPI-I-98-1-022, - `http://www.mpi-sb.mpg.de/~ziegler/TechRep.ps.gz'. + +File: gmp.info, Node: Converting Floats, Next: Float Arithmetic, Prev: Simultaneous Float Init & Assign, Up: Floating-point Functions - * Alfred J. Menezes, Paul C. van Oorschot and Scott A. Vanstone, - "Handbook of Applied Cryptography", - `http://cacr.math.uwaterloo.ca/hac/'. +Conversion Functions +==================== - * Henri Cohen, "A Course in Computational Algebraic Number Theory", - Graduate Texts in Mathematics number 138, Springer-Verlag, 1993. - Errata available online - `http://www.math.u-bordeaux.fr/~cohen' + - Function: double mpf_get_d (mpf_t OP) + Convert OP to a `double'. + - Function: double mpf_get_d_2exp (signed long int *EXP, mpf_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. This is similar to + the standard C function `frexp'. + + - Function: long mpf_get_si (mpf_t OP) + - Function: unsigned long mpf_get_ui (mpf_t OP) + Convert OP to a `long' or `unsigned long', truncating any fraction + part. If OP is too big for the return type, the result is + undefined. + + See also `mpf_fits_slong_p' and `mpf_fits_ulong_p' (*note + Miscellaneous Float Functions::). + + - 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. BASE can be 2 to + 36. Up to N_DIGITS digits will be generated. Trailing zeros are + not returned. No more digits than can be accurately represented + by OP are ever generated. If N_DIGITS is 0 then that accurate + maximum number of digits are generated. + + 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 N_DIGITS + 2 + bytes, that being enough for the mantissa, a possible minus sign, + and a null-terminator. When N_DIGITS is 0 to get all significant + digits, an application won't be able to know the space required, + and STR should be `NULL' in that case. + + The generated string is a fraction, with an implicit radix point + immediately to the left of the first digit. The applicable + exponent is written through the EXPPTR pointer. For example, the + number 3.1416 would be returned as string "31416" and exponent 1. + + When OP is zero, an empty string is produced and the exponent + returned is 0. + + A pointer to the result string is returned, being either the + allocated block or the given STR. +  -File: gmp.info, Node: Concept Index, Next: Function Index, Prev: References, Up: Top +File: gmp.info, Node: Float Arithmetic, Next: Float Comparison, Prev: Converting Floats, Up: Floating-point Functions -Concept Index -************* +Arithmetic Functions +==================== -* Menu: + - 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. -* ABI: ABI and ISA. -* About this manual: Introduction to GMP. -* alloca: Build Options. -* Allocation of memory: Custom Allocation. -* Anonymous FTP of latest version: Getting the Latest Version of GMP. -* Arithmetic functions <1>: Float Arithmetic. -* Arithmetic functions <2>: Rational Arithmetic. -* Arithmetic functions: Integer Arithmetic. -* Assignment functions <1>: Assigning Floats. -* Assignment functions: Assigning Integers. -* Basics: GMP Basics. -* Berkeley MP compatible functions: BSD Compatible Functions. -* Binomial coefficient functions: Number Theoretic Functions. -* Bit manipulation functions: Integer Logic and Bit Fiddling. -* Bit shift left: Integer Arithmetic. -* Bit shift right: Integer Division. -* Bits per limb: Useful Macros and Constants. -* BSD MP compatible functions: BSD Compatible Functions. -* Bug reporting: Reporting Bugs. -* Build notes for binary packaging: Notes for Package Builds. -* Build notes for particular systems: Notes for Particular Systems. -* Build options: Build Options. -* Build problems known: Known Build Problems. -* Comparison functions <1>: Integer Comparisons. -* Comparison functions <2>: Comparing Rationals. -* Comparison functions: Float Comparison. -* Compatibility with older versions: Compatibility with older versions. -* Conditions for copying GNU MP: Copying. -* Configuring GMP: Installing GMP. -* Constants: Useful Macros and Constants. -* Contributors: Contributors. -* Conventions for variables: GMP Variable Conventions. -* Conversion functions <1>: Converting Integers. -* Conversion functions: Converting Floats. -* Copying conditions: Copying. -* CPUs supported: Introduction to GMP. -* Custom allocation: Custom Allocation. -* Demonstration programs: Build Options. -* Division functions <1>: Integer Division. -* Division functions <2>: Rational Arithmetic. -* Division functions: Float Arithmetic. -* Exact division functions: Integer Division. -* Example programs: Build Options. -* Exponentiation functions <1>: Float Arithmetic. -* Exponentiation functions: Integer Exponentiation. -* Extended GCD: Number Theoretic Functions. -* Factorial functions: Number Theoretic Functions. -* Fibonacci sequence functions: Number Theoretic Functions. -* Float arithmetic functions: Float Arithmetic. -* Float assignment functions: Assigning Floats. -* Float comparison functions: Float Comparison. -* Float conversion functions: Converting Floats. -* Float functions: Floating-point Functions. -* Float init and assign functions: Simultaneous Float Init & Assign. -* Float initialization functions: Initializing Floats. -* Float input and output functions: I/O of Floats. -* Float miscellaneous functions: Miscellaneous Float Functions. -* Floating-point functions: Floating-point Functions. -* Floating-point number: Nomenclature and Types. -* FTP of latest version: Getting the Latest Version of GMP. -* Function classes: Function Classes. -* GMP version number: Useful Macros and Constants. -* gmp.h: GMP Basics. -* Greatest common divisor functions: Number Theoretic Functions. -* Home page: Introduction to GMP. -* I/O functions <1>: I/O of Rationals. -* I/O functions <2>: I/O of Integers. -* I/O functions: I/O of Floats. -* Initialization and assignment functions <1>: Initializing Rationals. -* Initialization and assignment functions <2>: Simultaneous Float Init & Assign. -* Initialization and assignment functions: Simultaneous Integer Init & Assign. -* Initialization functions <1>: Initializing Integers. -* Initialization functions: Initializing Floats. -* Input functions <1>: I/O of Floats. -* Input functions <2>: I/O of Rationals. -* Input functions: I/O of Integers. -* Installing GMP: Installing GMP. -* Integer: Nomenclature and Types. -* Integer arithmetic functions: Integer Arithmetic. -* Integer assignment functions: Assigning Integers. -* Integer bit manipulation functions: Integer Logic and Bit Fiddling. -* Integer comparison functions: Integer Comparisons. -* Integer conversion functions: Converting Integers. -* Integer division functions: Integer Division. -* Integer exponentiation functions: Integer Exponentiation. -* Integer functions: Integer Functions. -* Integer init and assign: Simultaneous Integer Init & Assign. -* Integer initialization functions: Initializing Integers. -* Integer input and output functions: I/O of Integers. -* Integer miscellaneous functions: Miscellaneous Integer Functions. -* Integer random number functions: Integer Random Numbers. -* Integer root functions: Integer Roots. -* Introduction: Introduction to GMP. -* ISA: ABI and ISA. -* Jabobi symbol functions: Number Theoretic Functions. -* Kronecker symbol functions: Number Theoretic Functions. -* Latest version of GMP: Getting the Latest Version of GMP. -* Least common multiple functions: Number Theoretic Functions. -* Libtool versioning: Notes for Package Builds. -* Limb: Nomenclature and Types. -* Limb size: Useful Macros and Constants. -* Logical functions: Integer Logic and Bit Fiddling. -* Low-level functions: Low-level Functions. -* Mailing list: Introduction to GMP. -* Memory allocation: Custom Allocation. -* Miscellaneous float functions: Miscellaneous Float Functions. -* Miscellaneous integer functions: Miscellaneous Integer Functions. -* Miscellaneous rational functions: Miscellaneous Rational Functions. -* Modular inverse functions: Number Theoretic Functions. -* mp.h: BSD Compatible Functions. -* Multi-threading: GMP and Reentrancy. -* Nomenclature: Nomenclature and Types. -* Number theoretic functions: Number Theoretic Functions. -* Numerator and denominator: Applying Integer Functions. -* Output functions <1>: I/O of Floats. -* Output functions <2>: I/O of Integers. -* Output functions: I/O of Rationals. -* Packaged builds: Notes for Package Builds. -* Parameter conventions: GMP Variable Conventions. -* Precision of floats: Floating-point Functions. -* Prime testing functions: Number Theoretic Functions. -* Random number functions <1>: Integer Random Numbers. -* Random number functions: Random Number Functions. -* Random number state: Random State Initialization. -* Rational arithmetic functions: Rational Arithmetic. -* Rational comparison functions: Comparing Rationals. -* Rational init and assign: Initializing Rationals. -* Rational input and output functions: I/O of Rationals. -* Rational miscellaneous functions: Miscellaneous Rational Functions. -* Rational number: Nomenclature and Types. -* Rational number functions: Rational Number Functions. -* Rational numerator and denominator: Applying Integer Functions. -* Reentrancy: GMP and Reentrancy. -* References: References. -* Reporting bugs: Reporting Bugs. -* Root extraction functions <1>: Float Arithmetic. -* Root extraction functions: Integer Roots. -* Stack overflow segfaults: Build Options. -* Stripped libraries: Known Build Problems. -* Thread safety: GMP and Reentrancy. -* Types: Nomenclature and Types. -* Upward compatibility: Compatibility with older versions. -* Useful macros and constants: Useful Macros and Constants. -* User-defined precision: Floating-point Functions. -* Variable conventions: GMP Variable Conventions. -* Version number: Useful Macros and Constants. -* Web page: Introduction to GMP. + - 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. + + - 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. + + 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 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 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 + OP2) + Set ROP to OP1 raised to the power OP2. + + - Function: void mpf_neg (mpf_t ROP, mpf_t OP) + Set ROP to -OP. + + - Function: void mpf_abs (mpf_t ROP, mpf_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. + + - 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. + + +File: gmp.info, Node: Float Comparison, Next: I/O of Floats, Prev: Float Arithmetic, Up: Floating-point Functions + +Comparison Functions +==================== + + - Function: int mpf_cmp (mpf_t OP1, mpf_t OP2) + - Function: int mpf_cmp_d (mpf_t OP1, double 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: 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. + + Caution: Currently only whole limbs are compared, and only in an + exact fashion. In the future values like 1000 and 0111 may be + considered the same to 3 bits (on the basis that their difference + is that small). + + - 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. This is abs(OP1-OP2)/OP1. + + - Macro: int mpf_sgn (mpf_t OP) + Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0. + + This function is actually implemented as a macro. It evaluates + its arguments multiple times. + + +File: gmp.info, Node: I/O of Floats, Next: Miscellaneous Float Functions, Prev: Float Comparison, Up: Floating-point Functions + +Input and Output Functions +========================== + + 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. + + 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. + + - Function: size_t mpf_out_str (FILE *STREAM, int BASE, size_t + N_DIGITS, mpf_t OP) + Print OP to STREAM, as a string of digits. Return the number of + bytes written, or if an error occurred, return 0. + + The mantissa is prefixed with an `0.' and is in the given BASE, + which may vary from 2 to 36. An exponent then printed, separated + by an `e', or if BASE is greater than 10 then by an `@'. The + exponent is always in decimal. The decimal point follows the + current locale, on systems providing `localeconv'. + + Up to N_DIGITS will be printed from the mantissa, except that no + more digits than are accurately representable by OP will be + printed. N_DIGITS can be 0 to select that accurate maximum. + + - Function: size_t mpf_inp_str (mpf_t ROP, FILE *STREAM, int BASE) + Read a string in base BASE from 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. The decimal point expected is taken from the current + locale, on systems providing `localeconv'. + + 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. + + 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. + + Return the number of bytes read, or if an error occurred, return 0.