=================================================================== RCS file: /home/cvs/OpenXM_contrib/gmp/Attic/gmp.info-3,v retrieving revision 1.1.1.1 retrieving revision 1.1.1.4 diff -u -p -r1.1.1.1 -r1.1.1.4 --- OpenXM_contrib/gmp/Attic/gmp.info-3 2000/01/10 15:35:21 1.1.1.1 +++ OpenXM_contrib/gmp/Attic/gmp.info-3 2003/08/25 16:06:02 1.1.1.4 @@ -1,259 +1,1173 @@ -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: Number Theoretic Functions, Next: Integer Comparisons, Prev: Integer Roots, Up: Integer Functions - Copyright (C) 1991, 1993, 1994, 1995, 1996 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. + - Function: void mpz_nextprime (mpz_t ROP, mpz_t OP) + Set ROP to the next prime greater than OP. + + 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. + + - 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. + + - 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. + + 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. + + - 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. + + If T is `NULL' then that value is not computed. + + - 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. + + - 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. + + - Function: int mpz_jacobi (mpz_t A, mpz_t B) + Calculate the Jacobi symbol (A/B). This is defined only for B odd. + + - 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. + + - 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. + + 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. + + 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: 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: void mpz_fac_ui (mpz_t ROP, unsigned long int OP) + Set ROP to OP!, the factorial of OP. + + - 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: 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]. + + 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: 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]. + + 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. + + 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. +  -File: gmp.info, Node: Function Index, Up: Top +File: gmp.info, Node: Integer Comparisons, Next: Integer Logic and Bit Fiddling, Prev: Number Theoretic Functions, Up: Integer Functions -Function and Type Index -*********************** +Comparison Functions +==================== + - 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. + + Note that `mpz_cmp_ui' and `mpz_cmp_si' are macros and will + evaluate their arguments more than once. + + - 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). + + Note that `mpz_cmpabs_si' is a macro and will evaluate its + arguments more than once. + + - Macro: int mpz_sgn (mpz_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 argument multiple times. + + +File: gmp.info, Node: Integer Logic and Bit Fiddling, Next: I/O of Integers, Prev: Integer Comparisons, Up: Integer Functions + +Logical and Bit Manipulation Functions +====================================== + + These functions behave as if twos complement arithmetic were used +(although sign-magnitude is the actual implementation). The least +significant bit is number 0. + + - Function: void mpz_and (mpz_t ROP, mpz_t OP1, mpz_t OP2) + Set ROP to OP1 logical-and OP2. + + - Function: void mpz_ior (mpz_t ROP, mpz_t OP1, mpz_t OP2) + Set ROP to OP1 inclusive-or OP2. + + - Function: void mpz_xor (mpz_t ROP, mpz_t OP1, mpz_t OP2) + Set ROP to OP1 exclusive-or OP2. + + - Function: void mpz_com (mpz_t ROP, mpz_t OP) + Set ROP to the one's complement of OP. + + - 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'. + + - 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: 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. + + If the bit at STARTING_BIT is already what's sought, then + STARTING_BIT is returned. + + 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. + + - Function: void mpz_setbit (mpz_t ROP, unsigned long int BIT_INDEX) + Set bit BIT_INDEX in ROP. + + - Function: void mpz_clrbit (mpz_t ROP, unsigned long int BIT_INDEX) + Clear bit BIT_INDEX in ROP. + + - Function: int mpz_tstbit (mpz_t OP, unsigned long int BIT_INDEX) + Test bit BIT_INDEX in OP and return 0 or 1 accordingly. + + +File: gmp.info, Node: I/O of Integers, Next: Integer Random Numbers, Prev: Integer Logic and Bit Fiddling, Up: Integer Functions + +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 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. + + Return the number of bytes written, or if an error occurred, + return 0. + + - 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. + + Return the number of bytes read, or if an error occurred, return 0. + + - 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 output can be read with `mpz_inp_raw'. + + Return the number of bytes written, or if an error occurred, + return 0. + + 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: size_t mpz_inp_raw (mpz_t ROP, FILE *STREAM) + Input from stdio stream STREAM in the format written by + `mpz_out_raw', and put the result in ROP. Return the number of + bytes read, or if an error occurred, return 0. + + This 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. + + +File: gmp.info, Node: Integer Random Numbers, Next: Integer Import and Export, Prev: I/O of Integers, Up: Integer Functions + +Random Number Functions +======================= + + The random number functions of GMP come in two groups; older function +that rely on a global state, and newer functions that accept a state +parameter that is read and modified. Please see the *Note Random +Number Functions:: for more information on how to use and not to use +random number functions. + + - 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. + + The variable STATE must be initialized by calling one of the + `gmp_randinit' functions (*Note Random State Initialization::) + before invoking this function. + + - 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. + + The variable STATE must be initialized by calling one of the + `gmp_randinit' functions (*Note Random State Initialization::) + before invoking this function. + + - 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. + + The variable STATE must be initialized by calling one of the + `gmp_randinit' functions (*Note Random State Initialization::) + before invoking this function. + + - 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. + + This function is obsolete. Use `mpz_urandomb' or `mpz_urandomm' + instead. + + - 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. + + This function is obsolete. Use `mpz_rrandomb' instead. + + +File: gmp.info, Node: Integer Import and Export, Next: Miscellaneous Integer Functions, Prev: Integer Random Numbers, Up: Integer Functions + +Integer Import and Export +========================= + + `mpz_t' variables can be converted to and from arbitrary words of +binary data with the following functions. + + - Function: void mpz_import (mpz_t ROP, size_t COUNT, int ORDER, int + SIZE, int ENDIAN, size_t NAILS, const void *OP) + Set ROP from an array of word data at OP. + + The parameters specify the format of the data. COUNT many words + are read, each SIZE bytes. ORDER can be 1 for most significant + word first or -1 for least significant first. Within each word + ENDIAN can be 1 for most significant byte first, -1 for least + significant first, or 0 for the native endianness of the host CPU. + The most significant NAILS bits of each word are skipped, this + can be 0 to use the full words. + + There are no data alignment restrictions on OP, any address is + allowed. + + Here's an example converting an array of `unsigned long' data, most + significant element first and host byte order within each value. + + unsigned long a[20]; + mpz_t z; + mpz_import (z, 20, 1, sizeof(a[0]), 0, 0, a); + + This example assumes the full `sizeof' bytes are used for data in + the given type, which is usually true, and certainly true for + `unsigned long' everywhere we know of. However on Cray vector + systems it may be noted that `short' and `int' are always stored + in 8 bytes (and with `sizeof' indicating that) but use only 32 or + 46 bits. The NAILS feature can account for this, by passing for + instance `8*sizeof(int)-INT_BIT'. + + - Function: void *mpz_export (void *ROP, size_t *COUNT, int ORDER, int + SIZE, int ENDIAN, size_t NAILS, mpz_t OP) + Fill ROP with word data from OP. + + The parameters specify the format of the data produced. Each word + will be SIZE bytes and ORDER can be 1 for most significant word + first or -1 for least significant first. Within each word ENDIAN + can be 1 for most significant byte first, -1 for least significant + first, or 0 for the native endianness of the host CPU. The most + significant NAILS bits of each word are unused and set to zero, + this can be 0 to produce full words. + + The number of words produced is written to `*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. + + 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. + + There are no data alignment restrictions on ROP, any address is + allowed. The sign of OP is ignored, just the absolute value is + used. + + 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. + + numb = 8*size - nail; + count = (mpz_sizeinbase (z, 2) + numb-1) / numb; + p = malloc (count * size); + + +File: gmp.info, Node: Miscellaneous Integer Functions, Prev: Integer Import and Export, Up: Integer Functions + +Miscellaneous Functions +======================= + + - 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. + + - 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. + + - 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. + + - 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. + + 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). + + +File: gmp.info, Node: Rational Number Functions, Next: Floating-point Functions, Prev: Integer Functions, Up: Top + +Rational Number Functions +************************* + + This chapter describes the GMP functions for performing arithmetic +on rational numbers. These functions start with the prefix `mpq_'. + + Rational numbers are stored in objects of type `mpq_t'. + + 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. + + 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: -* mp_limb_t: MP Basics. -* mpf_t: MP Basics. -* mpq_t: MP Basics. -* mpz_t: MP Basics. -* __GNU_MP_VERSION: MP Basics. -* __GNU_MP_VERSION_MINOR: MP Basics. -* _mpz_realloc: Initializing Integers. -* allocate_function: Custom Allocation. -* deallocate_function: Custom Allocation. -* gcd: BSD Compatible Functions. -* itom: BSD Compatible Functions. -* madd: BSD Compatible Functions. -* mcmp: BSD Compatible Functions. -* mdiv: BSD Compatible Functions. -* mfree: BSD Compatible Functions. -* min: BSD Compatible Functions. -* mout: BSD Compatible Functions. -* move: BSD Compatible Functions. -* mp_set_memory_functions: Custom Allocation. -* mpf_abs: Float Arithmetic. -* mpf_add: Float Arithmetic. -* mpf_add_ui: Float Arithmetic. -* mpf_clear: Initializing Floats. -* mpf_cmp: Float Comparison. -* mpf_cmp_si: Float Comparison. -* mpf_cmp_ui: Float Comparison. -* mpf_div: Float Arithmetic. -* mpf_div_2exp: Float Arithmetic. -* mpf_div_ui: Float Arithmetic. -* mpf_eq: Float Comparison. -* mpf_get_d: Converting Floats. -* mpf_get_prec: Initializing Floats. -* mpf_get_str: Converting Floats. -* mpf_init: Initializing Floats. -* mpf_init2: Initializing Floats. -* mpf_init_set: Simultaneous Float Init & Assign. -* mpf_init_set_d: Simultaneous Float Init & Assign. -* mpf_init_set_si: Simultaneous Float Init & Assign. -* mpf_init_set_str: Simultaneous Float Init & Assign. -* mpf_init_set_ui: Simultaneous Float Init & Assign. -* mpf_inp_str: I/O of Floats. -* mpf_mul: Float Arithmetic. -* mpf_mul_2exp: Float Arithmetic. -* mpf_mul_ui: Float Arithmetic. -* mpf_neg: Float Arithmetic. -* mpf_out_str: I/O of Floats. -* mpf_random2: Miscellaneous Float Functions. -* mpf_reldiff: Float Comparison. -* mpf_set: Assigning Floats. -* mpf_set_d: Assigning Floats. -* mpf_set_default_prec: Initializing Floats. -* mpf_set_prec: Initializing Floats. -* mpf_set_prec_raw: Initializing Floats. -* mpf_set_q: Assigning Floats. -* mpf_set_si: Assigning Floats. -* mpf_set_str: Assigning Floats. -* mpf_set_ui: Assigning Floats. -* mpf_set_z: Assigning Floats. -* mpf_sgn: Float Comparison. -* mpf_sqrt: Float Arithmetic. -* mpf_sqrt_ui: Float Arithmetic. -* mpf_sub: Float Arithmetic. -* mpf_sub_ui: Float Arithmetic. -* mpf_ui_div: Float Arithmetic. -* mpf_ui_sub: Float Arithmetic. -* mpn_add: Low-level Functions. -* mpn_add_1: Low-level Functions. -* mpn_add_n: Low-level Functions. -* mpn_addmul_1: Low-level Functions. -* mpn_bdivmod: Low-level Functions. -* mpn_cmp: Low-level Functions. -* mpn_divmod: Low-level Functions. -* mpn_divmod_1: Low-level Functions. -* mpn_divrem: Low-level Functions. -* mpn_divrem_1: Low-level Functions. -* mpn_gcd: Low-level Functions. -* mpn_gcd_1: Low-level Functions. -* mpn_gcdext: Low-level Functions. -* mpn_get_str: Low-level Functions. -* mpn_hamdist: Low-level Functions. -* mpn_lshift: Low-level Functions. -* mpn_mod_1: Low-level Functions. -* mpn_mul: Low-level Functions. -* mpn_mul_1: Low-level Functions. -* mpn_mul_n: Low-level Functions. -* mpn_perfect_square_p: Low-level Functions. -* mpn_popcount: Low-level Functions. -* mpn_preinv_mod_1: Low-level Functions. -* mpn_random2: Low-level Functions. -* mpn_rshift: Low-level Functions. -* mpn_scan0: Low-level Functions. -* mpn_scan1: Low-level Functions. -* mpn_set_str: Low-level Functions. -* mpn_sqrtrem: Low-level Functions. -* mpn_sub: Low-level Functions. -* mpn_sub_1: Low-level Functions. -* mpn_sub_n: Low-level Functions. -* mpn_submul_1: Low-level Functions. -* mpq_add: Assigning Rationals. -* mpq_canonicalize: Rational Number Functions. -* mpq_clear: Initializing Rationals. -* mpq_cmp: Comparing Rationals. -* mpq_cmp_ui: Comparing Rationals. -* mpq_denref: Applying Integer Functions. -* mpq_div: Assigning Rationals. -* mpq_equal: Comparing Rationals. -* mpq_get_d: Miscellaneous Rational Functions. -* mpq_get_den: Miscellaneous Rational Functions. -* mpq_get_num: Miscellaneous Rational Functions. -* mpq_init: Initializing Rationals. -* mpq_inv: Assigning Rationals. -* mpq_mul: Assigning Rationals. -* mpq_neg: Assigning Rationals. -* mpq_numref: Applying Integer Functions. -* mpq_set: Initializing Rationals. -* mpq_set_den: Miscellaneous Rational Functions. -* mpq_set_num: Miscellaneous Rational Functions. -* mpq_set_si: Initializing Rationals. -* mpq_set_ui: Initializing Rationals. -* mpq_set_z: Initializing Rationals. -* mpq_sgn: Comparing Rationals. -* mpq_sub: Assigning Rationals. -* mpz_abs: Integer Arithmetic. -* mpz_add: Integer Arithmetic. -* mpz_add_ui: Integer Arithmetic. -* mpz_and: Integer Logic and Bit Fiddling. -* mpz_array_init: Initializing Integers. -* mpz_cdiv_q: Integer Arithmetic. -* mpz_cdiv_q_ui: Integer Arithmetic. -* mpz_cdiv_qr: Integer Arithmetic. -* mpz_cdiv_qr_ui: Integer Arithmetic. -* mpz_cdiv_r: Integer Arithmetic. -* mpz_cdiv_r_ui: Integer Arithmetic. -* mpz_cdiv_ui: Integer Arithmetic. -* mpz_clear: Initializing Integers. -* mpz_clrbit: Integer Logic and Bit Fiddling. -* mpz_cmp: Comparison Functions. -* mpz_cmp_si: Comparison Functions. -* mpz_cmp_ui: Comparison Functions. -* mpz_com: Integer Logic and Bit Fiddling. -* mpz_divexact: Integer Arithmetic. -* mpz_fac_ui: Integer Arithmetic. -* mpz_fdiv_q: Integer Arithmetic. -* mpz_fdiv_q_2exp: Integer Arithmetic. -* mpz_fdiv_q_ui: Integer Arithmetic. -* mpz_fdiv_qr: Integer Arithmetic. -* mpz_fdiv_qr_ui: Integer Arithmetic. -* mpz_fdiv_r: Integer Arithmetic. -* mpz_fdiv_r_2exp: Integer Arithmetic. -* mpz_fdiv_r_ui: Integer Arithmetic. -* mpz_fdiv_ui: Integer Arithmetic. -* mpz_gcd: Integer Arithmetic. -* mpz_gcd_ui: Integer Arithmetic. -* mpz_gcdext: Integer Arithmetic. -* mpz_get_d: Converting Integers. -* mpz_get_si: Converting Integers. -* mpz_get_str: Converting Integers. -* mpz_get_ui: Converting Integers. -* mpz_hamdist: Integer Logic and Bit Fiddling. -* mpz_init: Initializing Integers. -* mpz_init_set: Simultaneous Integer Init & Assign. -* mpz_init_set_d: Simultaneous Integer Init & Assign. -* mpz_init_set_si: Simultaneous Integer Init & Assign. -* mpz_init_set_str: Simultaneous Integer Init & Assign. -* mpz_init_set_ui: Simultaneous Integer Init & Assign. -* mpz_inp_raw: I/O of Integers. -* mpz_inp_str: I/O of Integers. -* mpz_invert: Integer Arithmetic. -* mpz_ior: Integer Logic and Bit Fiddling. -* mpz_jacobi: Integer Arithmetic. -* mpz_legendre: Integer Arithmetic. -* mpz_mod: Integer Arithmetic. -* mpz_mod_ui: Integer Arithmetic. -* mpz_mul: Integer Arithmetic. -* mpz_mul_2exp: Integer Arithmetic. -* mpz_mul_ui: Integer Arithmetic. -* mpz_neg: Integer Arithmetic. -* mpz_out_raw: I/O of Integers. -* mpz_out_str: I/O of Integers. -* mpz_perfect_square_p: Integer Arithmetic. -* mpz_popcount: Integer Logic and Bit Fiddling. -* mpz_pow_ui: Integer Arithmetic. -* mpz_powm: Integer Arithmetic. -* mpz_powm_ui: Integer Arithmetic. -* mpz_probab_prime_p: Integer Arithmetic. -* mpz_random: Miscellaneous Integer Functions. -* mpz_random2: Miscellaneous Integer Functions. -* mpz_scan0: Integer Logic and Bit Fiddling. -* mpz_scan1: Integer Logic and Bit Fiddling. -* mpz_set: Assigning Integers. -* mpz_set_d: Assigning Integers. -* mpz_set_f: Assigning Integers. -* mpz_set_q: Assigning Integers. -* mpz_set_si: Assigning Integers. -* mpz_set_str: Assigning Integers. -* mpz_set_ui: Assigning Integers. -* mpz_setbit: Integer Logic and Bit Fiddling. -* mpz_sgn: Comparison Functions. -* mpz_size: Miscellaneous Integer Functions. -* mpz_sizeinbase: Miscellaneous Integer Functions. -* mpz_sqrt: Integer Arithmetic. -* mpz_sqrtrem: Integer Arithmetic. -* mpz_sub: Integer Arithmetic. -* mpz_sub_ui: Integer Arithmetic. -* mpz_tdiv_q: Integer Arithmetic. -* mpz_tdiv_q_2exp: Integer Arithmetic. -* mpz_tdiv_q_ui: Integer Arithmetic. -* mpz_tdiv_qr: Integer Arithmetic. -* mpz_tdiv_qr_ui: Integer Arithmetic. -* mpz_tdiv_r: Integer Arithmetic. -* mpz_tdiv_r_2exp: Integer Arithmetic. -* mpz_tdiv_r_ui: Integer Arithmetic. -* mpz_ui_pow_ui: Integer Arithmetic. -* msqrt: BSD Compatible Functions. -* msub: BSD Compatible Functions. -* mtox: BSD Compatible Functions. -* mult: BSD Compatible Functions. -* pow: BSD Compatible Functions. -* reallocate_function: Custom Allocation. -* rpow: BSD Compatible Functions. -* sdiv: BSD Compatible Functions. -* xtom: BSD Compatible Functions. +* Initializing Rationals:: +* Rational Conversions:: +* Rational Arithmetic:: +* Comparing Rationals:: +* Applying Integer Functions:: +* I/O of Rationals:: + +File: gmp.info, Node: Initializing Rationals, Next: Rational Conversions, Prev: Rational Number Functions, Up: Rational Number Functions + +Initialization and Assignment 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 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. + + - 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. + + - 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. + + - Function: int mpq_set_str (mpq_t ROP, char *STR, int BASE) + Set ROP from a null-terminated string STR in the given BASE. + + 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. + + The return value is 0 if the entire string is a valid number, or + -1 if not. + + - Function: void mpq_swap (mpq_t ROP1, mpq_t ROP2) + Swap the values ROP1 and ROP2 efficiently. + + +File: gmp.info, Node: Rational Conversions, Next: Rational Arithmetic, Prev: Initializing Rationals, Up: Rational Number Functions + +Conversion Functions +==================== + + - Function: double mpq_get_d (mpq_t OP) + Convert OP to a `double'. + + - 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. + + - 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'. + + If STR is `NULL', the result string is allocated using the current + allocation function (*note Custom Allocation::). The block will be + `strlen(str)+1' bytes, that being exactly enough for the string and + null-terminator. + + If STR is not `NULL', it should point to a block of storage large + enough for the result, that being + + mpz_sizeinbase (mpq_numref(OP), BASE) + + mpz_sizeinbase (mpq_denref(OP), BASE) + 3 + + The three extra bytes are for a possible minus sign, possible + slash, and the null-terminator. + + A pointer to the result string is returned, being either the + allocated block, or the given STR. + + +File: gmp.info, Node: Rational Arithmetic, Next: Comparing Rationals, Prev: Rational Conversions, Up: Rational Number Functions + +Arithmetic Functions +==================== + + - Function: void mpq_add (mpq_t SUM, mpq_t ADDEND1, mpq_t ADDEND2) + Set SUM to ADDEND1 + ADDEND2. + + - Function: void mpq_sub (mpq_t DIFFERENCE, mpq_t MINUEND, mpq_t + SUBTRAHEND) + Set DIFFERENCE to MINUEND - SUBTRAHEND. + + - Function: void mpq_mul (mpq_t PRODUCT, mpq_t MULTIPLIER, mpq_t + MULTIPLICAND) + Set PRODUCT to MULTIPLIER times MULTIPLICAND. + + - 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: void mpq_div (mpq_t QUOTIENT, mpq_t DIVIDEND, mpq_t + DIVISOR) + Set QUOTIENT to DIVIDEND/DIVISOR. + + - 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 mpq_neg (mpq_t NEGATED_OPERAND, mpq_t OPERAND) + Set NEGATED_OPERAND to -OPERAND. + + - Function: void mpq_abs (mpq_t ROP, mpq_t OP) + Set ROP to the absolute value of OP. + + - Function: void mpq_inv (mpq_t INVERTED_NUMBER, mpq_t NUMBER) + Set INVERTED_NUMBER to 1/NUMBER. If the new denominator is zero, + this routine will divide by zero. + + +File: gmp.info, Node: Comparing Rationals, Next: Applying Integer Functions, Prev: Rational Arithmetic, Up: Rational Number Functions + +Comparison Functions +==================== + + - 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. + + To determine if two rationals are equal, `mpq_equal' is faster than + `mpq_cmp'. + + - 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. + + NUM2 and DEN2 are allowed to have common factors. + + These functions are implemented as a macros and evaluate their + arguments multiple times. + + - Macro: int mpq_sgn (mpq_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. + + - 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. + + +File: gmp.info, Node: Applying Integer Functions, Next: I/O of Rationals, Prev: Comparing Rationals, Up: Rational Number Functions + +Applying Integer Functions to Rationals +======================================= + + 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: I/O of Rationals, Prev: Applying Integer Functions, Up: Rational Number Functions + +Input and Output Functions +========================== + + 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. + + Passing a `NULL' pointer for a STREAM argument to any of these +functions will make them read from `stdin' and write to `stdout', +respectively. + + - 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'. + + Return the number of bytes written, or if an error occurred, + return 0. + + - 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 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::). + + 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. + + +File: gmp.info, Node: Floating-point Functions, Next: Low-level Functions, Prev: Rational Number Functions, Up: Top + +Floating-point Functions +************************ + + GMP floating point numbers are stored in objects of type `mpf_t' and +functions operating on them have an `mpf_' prefix. + + 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. + + 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: Initializing Floats, Next: Assigning Floats, Prev: Floating-point Functions, Up: Floating-point Functions + +Initialization Functions +======================== + + - 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. + + - Function: unsigned long int mpf_get_default_prec (void) + Return the default default precision actually used. + + 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. + + - 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'. + + - 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. + + - 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. + + 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); + } + + 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. + + - Function: unsigned long int mpf_get_prec (mpf_t OP) + Return the current precision of OP, in bits. + + - 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. + + This function requires a call to `realloc', and so should not be + used in a tight loop. + + - 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. + + 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'. + + 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. + + 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. + + `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. + + `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. + + +File: gmp.info, Node: Assigning Floats, Next: Simultaneous Float Init & Assign, Prev: Initializing Floats, Up: Floating-point Functions + +Assignment Functions +==================== + + These functions assign new values to already initialized floats +(*note Initializing Floats::). + + - 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. + + - 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'. + + 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: Simultaneous Float Init & Assign, Next: Converting Floats, Prev: Assigning Floats, Up: Floating-point Functions + +Combined Initialization and Assignment Functions +================================================ + + For convenience, GMP provides a parallel series of +initialize-and-set functions which initialize the output and then store +the value there. These functions' names have the form `mpf_init_set...' + + 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! + + - 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 precision of ROP will be taken from the active default + precision, as set by `mpf_set_default_prec'. + + - 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. + + Note that ROP is initialized even if an error occurs. (I.e., you + have to call `mpf_clear' for it.) + + The precision of ROP will be taken from the active default + precision, as set by `mpf_set_default_prec'. + + +File: gmp.info, Node: Converting Floats, Next: Float Arithmetic, Prev: Simultaneous Float Init & Assign, Up: Floating-point Functions + +Conversion Functions +==================== + + - 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: Float Arithmetic, Next: Float Comparison, Prev: Converting Floats, Up: Floating-point Functions + +Arithmetic Functions +==================== + + - Function: void mpf_add (mpf_t ROP, mpf_t OP1, mpf_t OP2) + - Function: void mpf_add_ui (mpf_t ROP, mpf_t OP1, unsigned long int + OP2) + Set ROP to OP1 + OP2. + + - Function: void mpf_sub (mpf_t ROP, mpf_t OP1, mpf_t OP2) + - Function: void mpf_ui_sub (mpf_t ROP, unsigned long int OP1, mpf_t + 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.