Annotation of OpenXM_contrib/gmp/gmp.info-3, Revision 1.1.1.4
1.1.1.4 ! ohara 1: This is gmp.info, produced by makeinfo version 4.2 from gmp.texi.
1.1 maekawa 2:
1.1.1.4 ! ohara 3: This manual describes how to install and use the GNU multiple precision
! 4: arithmetic library, version 4.1.2.
! 5:
! 6: Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
! 7: 2001, 2002 Free Software Foundation, Inc.
! 8:
! 9: Permission is granted to copy, distribute and/or modify this
! 10: document under the terms of the GNU Free Documentation License, Version
! 11: 1.1 or any later version published by the Free Software Foundation;
! 12: with no Invariant Sections, with the Front-Cover Texts being "A GNU
! 13: Manual", and with the Back-Cover Texts being "You have freedom to copy
! 14: and modify this GNU Manual, like GNU software". A copy of the license
! 15: is included in *Note GNU Free Documentation License::.
1.1.1.2 maekawa 16: INFO-DIR-SECTION GNU libraries
1.1 maekawa 17: START-INFO-DIR-ENTRY
1.1.1.2 maekawa 18: * gmp: (gmp). GNU Multiple Precision Arithmetic Library.
1.1 maekawa 19: END-INFO-DIR-ENTRY
20:
1.1.1.4 ! ohara 21:
! 22: File: gmp.info, Node: Number Theoretic Functions, Next: Integer Comparisons, Prev: Integer Roots, Up: Integer Functions
1.1 maekawa 23:
1.1.1.4 ! ohara 24: Number Theoretic Functions
! 25: ==========================
1.1 maekawa 26:
1.1.1.4 ! ohara 27: - Function: int mpz_probab_prime_p (mpz_t N, int REPS)
! 28: Determine whether N is prime. Return 2 if N is definitely prime,
! 29: return 1 if N is probably prime (without being certain), or return
! 30: 0 if N is definitely composite.
! 31:
! 32: This function does some trial divisions, then some Miller-Rabin
! 33: probabilistic primality tests. REPS controls how many such tests
! 34: are done, 5 to 10 is a reasonable number, more will reduce the
! 35: chances of a composite being returned as "probably prime".
! 36:
! 37: Miller-Rabin and similar tests can be more properly called
! 38: compositeness tests. Numbers which fail are known to be composite
! 39: but those which pass might be prime or might be composite. Only a
! 40: few composites pass, hence those which pass are considered
! 41: probably prime.
! 42:
! 43: - Function: void mpz_nextprime (mpz_t ROP, mpz_t OP)
! 44: Set ROP to the next prime greater than OP.
! 45:
! 46: This function uses a probabilistic algorithm to identify primes.
! 47: For practical purposes it's adequate, the chance of a composite
! 48: passing will be extremely small.
! 49:
! 50: - Function: void mpz_gcd (mpz_t ROP, mpz_t OP1, mpz_t OP2)
! 51: Set ROP to the greatest common divisor of OP1 and OP2. The result
! 52: is always positive even if one or both input operands are negative.
! 53:
! 54: - Function: unsigned long int mpz_gcd_ui (mpz_t ROP, mpz_t OP1,
! 55: unsigned long int OP2)
! 56: Compute the greatest common divisor of OP1 and OP2. If ROP is not
! 57: `NULL', store the result there.
! 58:
! 59: If the result is small enough to fit in an `unsigned long int', it
! 60: is returned. If the result does not fit, 0 is returned, and the
! 61: result is equal to the argument OP1. Note that the result will
! 62: always fit if OP2 is non-zero.
! 63:
! 64: - Function: void mpz_gcdext (mpz_t G, mpz_t S, mpz_t T, mpz_t A, mpz_t
! 65: B)
! 66: Set G to the greatest common divisor of A and B, and in addition
! 67: set S and T to coefficients satisfying A*S + B*T = G. G is always
! 68: positive, even if one or both of A and B are negative.
! 69:
! 70: If T is `NULL' then that value is not computed.
! 71:
! 72: - Function: void mpz_lcm (mpz_t ROP, mpz_t OP1, mpz_t OP2)
! 73: - Function: void mpz_lcm_ui (mpz_t ROP, mpz_t OP1, unsigned long OP2)
! 74: Set ROP to the least common multiple of OP1 and OP2. ROP is
! 75: always positive, irrespective of the signs of OP1 and OP2. ROP
! 76: will be zero if either OP1 or OP2 is zero.
! 77:
! 78: - Function: int mpz_invert (mpz_t ROP, mpz_t OP1, mpz_t OP2)
! 79: Compute the inverse of OP1 modulo OP2 and put the result in ROP.
! 80: If the inverse exists, the return value is non-zero and ROP will
! 81: satisfy 0 <= ROP < OP2. If an inverse doesn't exist the return
! 82: value is zero and ROP is undefined.
! 83:
! 84: - Function: int mpz_jacobi (mpz_t A, mpz_t B)
! 85: Calculate the Jacobi symbol (A/B). This is defined only for B odd.
! 86:
! 87: - Function: int mpz_legendre (mpz_t A, mpz_t P)
! 88: Calculate the Legendre symbol (A/P). This is defined only for P
! 89: an odd positive prime, and for such P it's identical to the Jacobi
! 90: symbol.
! 91:
! 92: - Function: int mpz_kronecker (mpz_t A, mpz_t B)
! 93: - Function: int mpz_kronecker_si (mpz_t A, long B)
! 94: - Function: int mpz_kronecker_ui (mpz_t A, unsigned long B)
! 95: - Function: int mpz_si_kronecker (long A, mpz_t B)
! 96: - Function: int mpz_ui_kronecker (unsigned long A, mpz_t B)
! 97: Calculate the Jacobi symbol (A/B) with the Kronecker extension
! 98: (a/2)=(2/a) when a odd, or (a/2)=0 when a even.
! 99:
! 100: When B is odd the Jacobi symbol and Kronecker symbol are
! 101: identical, so `mpz_kronecker_ui' etc can be used for mixed
! 102: precision Jacobi symbols too.
! 103:
! 104: For more information see Henri Cohen section 1.4.2 (*note
! 105: References::), or any number theory textbook. See also the
! 106: example program `demos/qcn.c' which uses `mpz_kronecker_ui'.
! 107:
! 108: - Function: unsigned long int mpz_remove (mpz_t ROP, mpz_t OP, mpz_t F)
! 109: Remove all occurrences of the factor F from OP and store the
! 110: result in ROP. The return value is how many such occurrences were
! 111: removed.
! 112:
! 113: - Function: void mpz_fac_ui (mpz_t ROP, unsigned long int OP)
! 114: Set ROP to OP!, the factorial of OP.
! 115:
! 116: - Function: void mpz_bin_ui (mpz_t ROP, mpz_t N, unsigned long int K)
! 117: - Function: void mpz_bin_uiui (mpz_t ROP, unsigned long int N,
! 118: unsigned long int K)
! 119: Compute the binomial coefficient N over K and store the result in
! 120: ROP. Negative values of N are supported by `mpz_bin_ui', using
! 121: the identity bin(-n,k) = (-1)^k * bin(n+k-1,k), see Knuth volume 1
! 122: section 1.2.6 part G.
! 123:
! 124: - Function: void mpz_fib_ui (mpz_t FN, unsigned long int N)
! 125: - Function: void mpz_fib2_ui (mpz_t FN, mpz_t FNSUB1, unsigned long
! 126: int N)
! 127: `mpz_fib_ui' sets FN to to F[n], the N'th Fibonacci number.
! 128: `mpz_fib2_ui' sets FN to F[n], and FNSUB1 to F[n-1].
! 129:
! 130: These functions are designed for calculating isolated Fibonacci
! 131: numbers. When a sequence of values is wanted it's best to start
! 132: with `mpz_fib2_ui' and iterate the defining F[n+1]=F[n]+F[n-1] or
! 133: similar.
! 134:
! 135: - Function: void mpz_lucnum_ui (mpz_t LN, unsigned long int N)
! 136: - Function: void mpz_lucnum2_ui (mpz_t LN, mpz_t LNSUB1, unsigned long
! 137: int N)
! 138: `mpz_lucnum_ui' sets LN to to L[n], the N'th Lucas number.
! 139: `mpz_lucnum2_ui' sets LN to L[n], and LNSUB1 to L[n-1].
! 140:
! 141: These functions are designed for calculating isolated Lucas
! 142: numbers. When a sequence of values is wanted it's best to start
! 143: with `mpz_lucnum2_ui' and iterate the defining L[n+1]=L[n]+L[n-1]
! 144: or similar.
! 145:
! 146: The Fibonacci numbers and Lucas numbers are related sequences, so
! 147: it's never necessary to call both `mpz_fib2_ui' and
! 148: `mpz_lucnum2_ui'. The formulas for going from Fibonacci to Lucas
! 149: can be found in *Note Lucas Numbers Algorithm::, the reverse is
! 150: straightforward too.
1.1.1.2 maekawa 151:
152:
1.1.1.4 ! ohara 153: File: gmp.info, Node: Integer Comparisons, Next: Integer Logic and Bit Fiddling, Prev: Number Theoretic Functions, Up: Integer Functions
1.1.1.2 maekawa 154:
1.1.1.4 ! ohara 155: Comparison Functions
! 156: ====================
1.1 maekawa 157:
1.1.1.4 ! ohara 158: - Function: int mpz_cmp (mpz_t OP1, mpz_t OP2)
! 159: - Function: int mpz_cmp_d (mpz_t OP1, double OP2)
! 160: - Macro: int mpz_cmp_si (mpz_t OP1, signed long int OP2)
! 161: - Macro: int mpz_cmp_ui (mpz_t OP1, unsigned long int OP2)
! 162: Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
! 163: if OP1 = OP2, or a negative value if OP1 < OP2.
! 164:
! 165: Note that `mpz_cmp_ui' and `mpz_cmp_si' are macros and will
! 166: evaluate their arguments more than once.
! 167:
! 168: - Function: int mpz_cmpabs (mpz_t OP1, mpz_t OP2)
! 169: - Function: int mpz_cmpabs_d (mpz_t OP1, double OP2)
! 170: - Function: int mpz_cmpabs_ui (mpz_t OP1, unsigned long int OP2)
! 171: Compare the absolute values of OP1 and OP2. Return a positive
! 172: value if abs(OP1) > abs(OP2), zero if abs(OP1) = abs(OP2), or a
! 173: negative value if abs(OP1) < abs(OP2).
1.1.1.2 maekawa 174:
1.1.1.4 ! ohara 175: Note that `mpz_cmpabs_si' is a macro and will evaluate its
! 176: arguments more than once.
1.1.1.2 maekawa 177:
1.1.1.4 ! ohara 178: - Macro: int mpz_sgn (mpz_t OP)
! 179: Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.
1.1 maekawa 180:
1.1.1.4 ! ohara 181: This function is actually implemented as a macro. It evaluates
! 182: its argument multiple times.
1.1.1.2 maekawa 183:
184:
1.1.1.4 ! ohara 185: File: gmp.info, Node: Integer Logic and Bit Fiddling, Next: I/O of Integers, Prev: Integer Comparisons, Up: Integer Functions
1.1.1.2 maekawa 186:
1.1.1.4 ! ohara 187: Logical and Bit Manipulation Functions
! 188: ======================================
1.1.1.2 maekawa 189:
1.1.1.4 ! ohara 190: These functions behave as if twos complement arithmetic were used
! 191: (although sign-magnitude is the actual implementation). The least
! 192: significant bit is number 0.
! 193:
! 194: - Function: void mpz_and (mpz_t ROP, mpz_t OP1, mpz_t OP2)
! 195: Set ROP to OP1 logical-and OP2.
! 196:
! 197: - Function: void mpz_ior (mpz_t ROP, mpz_t OP1, mpz_t OP2)
! 198: Set ROP to OP1 inclusive-or OP2.
! 199:
! 200: - Function: void mpz_xor (mpz_t ROP, mpz_t OP1, mpz_t OP2)
! 201: Set ROP to OP1 exclusive-or OP2.
! 202:
! 203: - Function: void mpz_com (mpz_t ROP, mpz_t OP)
! 204: Set ROP to the one's complement of OP.
! 205:
! 206: - Function: unsigned long int mpz_popcount (mpz_t OP)
! 207: If OP>=0, return the population count of OP, which is the number
! 208: of 1 bits in the binary representation. If OP<0, the number of 1s
! 209: is infinite, and the return value is MAX_ULONG, the largest
! 210: possible `unsigned long'.
! 211:
! 212: - Function: unsigned long int mpz_hamdist (mpz_t OP1, mpz_t OP2)
! 213: If OP1 and OP2 are both >=0 or both <0, return the hamming
! 214: distance between the two operands, which is the number of bit
! 215: positions where OP1 and OP2 have different bit values. If one
! 216: operand is >=0 and the other <0 then the number of bits different
! 217: is infinite, and the return value is MAX_ULONG, the largest
! 218: possible `unsigned long'.
! 219:
! 220: - Function: unsigned long int mpz_scan0 (mpz_t OP, unsigned long int
! 221: STARTING_BIT)
! 222: - Function: unsigned long int mpz_scan1 (mpz_t OP, unsigned long int
! 223: STARTING_BIT)
! 224: Scan OP, starting from bit STARTING_BIT, towards more significant
! 225: bits, until the first 0 or 1 bit (respectively) is found. Return
! 226: the index of the found bit.
! 227:
! 228: If the bit at STARTING_BIT is already what's sought, then
! 229: STARTING_BIT is returned.
! 230:
! 231: If there's no bit found, then MAX_ULONG is returned. This will
! 232: happen in `mpz_scan0' past the end of a positive number, or
! 233: `mpz_scan1' past the end of a negative.
1.1.1.2 maekawa 234:
1.1.1.4 ! ohara 235: - Function: void mpz_setbit (mpz_t ROP, unsigned long int BIT_INDEX)
! 236: Set bit BIT_INDEX in ROP.
1.1.1.2 maekawa 237:
1.1.1.4 ! ohara 238: - Function: void mpz_clrbit (mpz_t ROP, unsigned long int BIT_INDEX)
! 239: Clear bit BIT_INDEX in ROP.
1.1.1.2 maekawa 240:
1.1.1.4 ! ohara 241: - Function: int mpz_tstbit (mpz_t OP, unsigned long int BIT_INDEX)
! 242: Test bit BIT_INDEX in OP and return 0 or 1 accordingly.
1.1.1.2 maekawa 243:
1.1.1.4 ! ohara 244:
! 245: File: gmp.info, Node: I/O of Integers, Next: Integer Random Numbers, Prev: Integer Logic and Bit Fiddling, Up: Integer Functions
1.1.1.2 maekawa 246:
1.1.1.4 ! ohara 247: Input and Output Functions
! 248: ==========================
1.1.1.2 maekawa 249:
1.1.1.4 ! ohara 250: Functions that perform input from a stdio stream, and functions that
! 251: output to a stdio stream. Passing a `NULL' pointer for a STREAM
! 252: argument to any of these functions will make them read from `stdin' and
! 253: write to `stdout', respectively.
! 254:
! 255: When using any of these functions, it is a good idea to include
! 256: `stdio.h' before `gmp.h', since that will allow `gmp.h' to define
! 257: prototypes for these functions.
! 258:
! 259: - Function: size_t mpz_out_str (FILE *STREAM, int BASE, mpz_t OP)
! 260: Output OP on stdio stream STREAM, as a string of digits in base
! 261: BASE. The base may vary from 2 to 36.
! 262:
! 263: Return the number of bytes written, or if an error occurred,
! 264: return 0.
! 265:
! 266: - Function: size_t mpz_inp_str (mpz_t ROP, FILE *STREAM, int BASE)
! 267: Input a possibly white-space preceded string in base BASE from
! 268: stdio stream STREAM, and put the read integer in ROP. The base
! 269: may vary from 2 to 36. If BASE is 0, the actual base is
! 270: determined from the leading characters: if the first two
! 271: characters are `0x' or `0X', hexadecimal is assumed, otherwise if
! 272: the first character is `0', octal is assumed, otherwise decimal is
! 273: assumed.
! 274:
! 275: Return the number of bytes read, or if an error occurred, return 0.
! 276:
! 277: - Function: size_t mpz_out_raw (FILE *STREAM, mpz_t OP)
! 278: Output OP on stdio stream STREAM, in raw binary format. The
! 279: integer is written in a portable format, with 4 bytes of size
! 280: information, and that many bytes of limbs. Both the size and the
! 281: limbs are written in decreasing significance order (i.e., in
! 282: big-endian).
! 283:
! 284: The output can be read with `mpz_inp_raw'.
! 285:
! 286: Return the number of bytes written, or if an error occurred,
! 287: return 0.
! 288:
! 289: The output of this can not be read by `mpz_inp_raw' from GMP 1,
! 290: because of changes necessary for compatibility between 32-bit and
! 291: 64-bit machines.
! 292:
! 293: - Function: size_t mpz_inp_raw (mpz_t ROP, FILE *STREAM)
! 294: Input from stdio stream STREAM in the format written by
! 295: `mpz_out_raw', and put the result in ROP. Return the number of
! 296: bytes read, or if an error occurred, return 0.
! 297:
! 298: This routine can read the output from `mpz_out_raw' also from GMP
! 299: 1, in spite of changes necessary for compatibility between 32-bit
! 300: and 64-bit machines.
1.1.1.2 maekawa 301:
1.1.1.4 ! ohara 302:
! 303: File: gmp.info, Node: Integer Random Numbers, Next: Integer Import and Export, Prev: I/O of Integers, Up: Integer Functions
1.1.1.2 maekawa 304:
1.1.1.4 ! ohara 305: Random Number Functions
! 306: =======================
1.1.1.2 maekawa 307:
1.1.1.4 ! ohara 308: The random number functions of GMP come in two groups; older function
! 309: that rely on a global state, and newer functions that accept a state
! 310: parameter that is read and modified. Please see the *Note Random
! 311: Number Functions:: for more information on how to use and not to use
! 312: random number functions.
! 313:
! 314: - Function: void mpz_urandomb (mpz_t ROP, gmp_randstate_t STATE,
! 315: unsigned long int N)
! 316: Generate a uniformly distributed random integer in the range 0 to
! 317: 2^N-1, inclusive.
! 318:
! 319: The variable STATE must be initialized by calling one of the
! 320: `gmp_randinit' functions (*Note Random State Initialization::)
! 321: before invoking this function.
! 322:
! 323: - Function: void mpz_urandomm (mpz_t ROP, gmp_randstate_t STATE, mpz_t
! 324: N)
! 325: Generate a uniform random integer in the range 0 to N-1, inclusive.
! 326:
! 327: The variable STATE must be initialized by calling one of the
! 328: `gmp_randinit' functions (*Note Random State Initialization::)
! 329: before invoking this function.
! 330:
! 331: - Function: void mpz_rrandomb (mpz_t ROP, gmp_randstate_t STATE,
! 332: unsigned long int N)
! 333: Generate a random integer with long strings of zeros and ones in
! 334: the binary representation. Useful for testing functions and
! 335: algorithms, since this kind of random numbers have proven to be
! 336: more likely to trigger corner-case bugs. The random number will
! 337: be in the range 0 to 2^N-1, inclusive.
! 338:
! 339: The variable STATE must be initialized by calling one of the
! 340: `gmp_randinit' functions (*Note Random State Initialization::)
! 341: before invoking this function.
! 342:
! 343: - Function: void mpz_random (mpz_t ROP, mp_size_t MAX_SIZE)
! 344: Generate a random integer of at most MAX_SIZE limbs. The generated
! 345: random number doesn't satisfy any particular requirements of
! 346: randomness. Negative random numbers are generated when MAX_SIZE
! 347: is negative.
! 348:
! 349: This function is obsolete. Use `mpz_urandomb' or `mpz_urandomm'
! 350: instead.
! 351:
! 352: - Function: void mpz_random2 (mpz_t ROP, mp_size_t MAX_SIZE)
! 353: Generate a random integer of at most MAX_SIZE limbs, with long
! 354: strings of zeros and ones in the binary representation. Useful
! 355: for testing functions and algorithms, since this kind of random
! 356: numbers have proven to be more likely to trigger corner-case bugs.
! 357: Negative random numbers are generated when MAX_SIZE is negative.
1.1.1.2 maekawa 358:
1.1.1.4 ! ohara 359: This function is obsolete. Use `mpz_rrandomb' instead.
1.1.1.2 maekawa 360:
1.1.1.4 ! ohara 361:
! 362: File: gmp.info, Node: Integer Import and Export, Next: Miscellaneous Integer Functions, Prev: Integer Random Numbers, Up: Integer Functions
1.1.1.2 maekawa 363:
1.1.1.4 ! ohara 364: Integer Import and Export
! 365: =========================
1.1.1.2 maekawa 366:
1.1.1.4 ! ohara 367: `mpz_t' variables can be converted to and from arbitrary words of
! 368: binary data with the following functions.
1.1.1.2 maekawa 369:
1.1.1.4 ! ohara 370: - Function: void mpz_import (mpz_t ROP, size_t COUNT, int ORDER, int
! 371: SIZE, int ENDIAN, size_t NAILS, const void *OP)
! 372: Set ROP from an array of word data at OP.
! 373:
! 374: The parameters specify the format of the data. COUNT many words
! 375: are read, each SIZE bytes. ORDER can be 1 for most significant
! 376: word first or -1 for least significant first. Within each word
! 377: ENDIAN can be 1 for most significant byte first, -1 for least
! 378: significant first, or 0 for the native endianness of the host CPU.
! 379: The most significant NAILS bits of each word are skipped, this
! 380: can be 0 to use the full words.
! 381:
! 382: There are no data alignment restrictions on OP, any address is
! 383: allowed.
! 384:
! 385: Here's an example converting an array of `unsigned long' data, most
! 386: significant element first and host byte order within each value.
! 387:
! 388: unsigned long a[20];
! 389: mpz_t z;
! 390: mpz_import (z, 20, 1, sizeof(a[0]), 0, 0, a);
! 391:
! 392: This example assumes the full `sizeof' bytes are used for data in
! 393: the given type, which is usually true, and certainly true for
! 394: `unsigned long' everywhere we know of. However on Cray vector
! 395: systems it may be noted that `short' and `int' are always stored
! 396: in 8 bytes (and with `sizeof' indicating that) but use only 32 or
! 397: 46 bits. The NAILS feature can account for this, by passing for
! 398: instance `8*sizeof(int)-INT_BIT'.
! 399:
! 400: - Function: void *mpz_export (void *ROP, size_t *COUNT, int ORDER, int
! 401: SIZE, int ENDIAN, size_t NAILS, mpz_t OP)
! 402: Fill ROP with word data from OP.
! 403:
! 404: The parameters specify the format of the data produced. Each word
! 405: will be SIZE bytes and ORDER can be 1 for most significant word
! 406: first or -1 for least significant first. Within each word ENDIAN
! 407: can be 1 for most significant byte first, -1 for least significant
! 408: first, or 0 for the native endianness of the host CPU. The most
! 409: significant NAILS bits of each word are unused and set to zero,
! 410: this can be 0 to produce full words.
! 411:
! 412: The number of words produced is written to `*COUNT'. ROP must
! 413: have enough space for the data, or if ROP is `NULL' then a result
! 414: array of the necessary size is allocated using the current GMP
! 415: allocation function (*note Custom Allocation::). In either case
! 416: the return value is the destination used, ROP or the allocated
! 417: block.
! 418:
! 419: If OP is non-zero then the most significant word produced will be
! 420: non-zero. If OP is zero then the count returned will be zero and
! 421: nothing written to ROP. If ROP is `NULL' in this case, no block
! 422: is allocated, just `NULL' is returned.
! 423:
! 424: There are no data alignment restrictions on ROP, any address is
! 425: allowed. The sign of OP is ignored, just the absolute value is
! 426: used.
! 427:
! 428: When an application is allocating space itself the required size
! 429: can be determined with a calculation like the following. Since
! 430: `mpz_sizeinbase' always returns at least 1, `count' here will be
! 431: at least one, which avoids any portability problems with
! 432: `malloc(0)', though if `z' is zero no space at all is actually
! 433: needed.
! 434:
! 435: numb = 8*size - nail;
! 436: count = (mpz_sizeinbase (z, 2) + numb-1) / numb;
! 437: p = malloc (count * size);
1.1.1.2 maekawa 438:
1.1.1.4 ! ohara 439:
! 440: File: gmp.info, Node: Miscellaneous Integer Functions, Prev: Integer Import and Export, Up: Integer Functions
1.1.1.2 maekawa 441:
1.1.1.4 ! ohara 442: Miscellaneous Functions
! 443: =======================
1.1.1.2 maekawa 444:
1.1.1.4 ! ohara 445: - Function: int mpz_fits_ulong_p (mpz_t OP)
! 446: - Function: int mpz_fits_slong_p (mpz_t OP)
! 447: - Function: int mpz_fits_uint_p (mpz_t OP)
! 448: - Function: int mpz_fits_sint_p (mpz_t OP)
! 449: - Function: int mpz_fits_ushort_p (mpz_t OP)
! 450: - Function: int mpz_fits_sshort_p (mpz_t OP)
! 451: Return non-zero iff the value of OP fits in an `unsigned long int',
! 452: `signed long int', `unsigned int', `signed int', `unsigned short
! 453: int', or `signed short int', respectively. Otherwise, return zero.
! 454:
! 455: - Macro: int mpz_odd_p (mpz_t OP)
! 456: - Macro: int mpz_even_p (mpz_t OP)
! 457: Determine whether OP is odd or even, respectively. Return
! 458: non-zero if yes, zero if no. These macros evaluate their argument
! 459: more than once.
! 460:
! 461: - Function: size_t mpz_size (mpz_t OP)
! 462: Return the size of OP measured in number of limbs. If OP is zero,
! 463: the returned value will be zero.
! 464:
! 465: - Function: size_t mpz_sizeinbase (mpz_t OP, int BASE)
! 466: Return the size of OP measured in number of digits in base BASE.
! 467: The base may vary from 2 to 36. The sign of OP is ignored, just
! 468: the absolute value is used. The result will be exact or 1 too
! 469: big. If BASE is a power of 2, the result will always be exact.
! 470: If OP is zero the return value is always 1.
! 471:
! 472: This function is useful in order to allocate the right amount of
! 473: space before converting OP to a string. The right amount of
! 474: allocation is normally two more than the value returned by
! 475: `mpz_sizeinbase' (one extra for a minus sign and one for the
! 476: null-terminator).
1.1.1.2 maekawa 477:
478:
1.1.1.4 ! ohara 479: File: gmp.info, Node: Rational Number Functions, Next: Floating-point Functions, Prev: Integer Functions, Up: Top
1.1.1.2 maekawa 480:
1.1.1.4 ! ohara 481: Rational Number Functions
! 482: *************************
1.1.1.2 maekawa 483:
1.1.1.4 ! ohara 484: This chapter describes the GMP functions for performing arithmetic
! 485: on rational numbers. These functions start with the prefix `mpq_'.
1.1.1.2 maekawa 486:
1.1.1.4 ! ohara 487: Rational numbers are stored in objects of type `mpq_t'.
1.1.1.2 maekawa 488:
1.1.1.4 ! ohara 489: All rational arithmetic functions assume operands have a canonical
! 490: form, and canonicalize their result. The canonical from means that the
! 491: denominator and the numerator have no common factors, and that the
! 492: denominator is positive. Zero has the unique representation 0/1.
1.1.1.2 maekawa 493:
1.1.1.4 ! ohara 494: Pure assignment functions do not canonicalize the assigned variable.
! 495: It is the responsibility of the user to canonicalize the assigned
! 496: variable before any arithmetic operations are performed on that
! 497: variable.
1.1.1.2 maekawa 498:
1.1.1.4 ! ohara 499: - Function: void mpq_canonicalize (mpq_t OP)
! 500: Remove any factors that are common to the numerator and
! 501: denominator of OP, and make the denominator positive.
1.1.1.2 maekawa 502:
1.1.1.4 ! ohara 503: * Menu:
1.1.1.2 maekawa 504:
1.1.1.4 ! ohara 505: * Initializing Rationals::
! 506: * Rational Conversions::
! 507: * Rational Arithmetic::
! 508: * Comparing Rationals::
! 509: * Applying Integer Functions::
! 510: * I/O of Rationals::
1.1.1.2 maekawa 511:
1.1.1.4 ! ohara 512:
! 513: File: gmp.info, Node: Initializing Rationals, Next: Rational Conversions, Prev: Rational Number Functions, Up: Rational Number Functions
1.1.1.2 maekawa 514:
1.1.1.4 ! ohara 515: Initialization and Assignment Functions
! 516: =======================================
1.1.1.2 maekawa 517:
1.1.1.4 ! ohara 518: - Function: void mpq_init (mpq_t DEST_RATIONAL)
! 519: Initialize DEST_RATIONAL and set it to 0/1. Each variable should
! 520: normally only be initialized once, or at least cleared out (using
! 521: the function `mpq_clear') between each initialization.
! 522:
! 523: - Function: void mpq_clear (mpq_t RATIONAL_NUMBER)
! 524: Free the space occupied by RATIONAL_NUMBER. Make sure to call this
! 525: function for all `mpq_t' variables when you are done with them.
! 526:
! 527: - Function: void mpq_set (mpq_t ROP, mpq_t OP)
! 528: - Function: void mpq_set_z (mpq_t ROP, mpz_t OP)
! 529: Assign ROP from OP.
! 530:
! 531: - Function: void mpq_set_ui (mpq_t ROP, unsigned long int OP1,
! 532: unsigned long int OP2)
! 533: - Function: void mpq_set_si (mpq_t ROP, signed long int OP1, unsigned
! 534: long int OP2)
! 535: Set the value of ROP to OP1/OP2. Note that if OP1 and OP2 have
! 536: common factors, ROP has to be passed to `mpq_canonicalize' before
! 537: any operations are performed on ROP.
! 538:
! 539: - Function: int mpq_set_str (mpq_t ROP, char *STR, int BASE)
! 540: Set ROP from a null-terminated string STR in the given BASE.
! 541:
! 542: The string can be an integer like "41" or a fraction like
! 543: "41/152". The fraction must be in canonical form (*note Rational
! 544: Number Functions::), or if not then `mpq_canonicalize' must be
! 545: called.
! 546:
! 547: The numerator and optional denominator are parsed the same as in
! 548: `mpz_set_str' (*note Assigning Integers::). White space is
! 549: allowed in the string, and is simply ignored. The BASE can vary
! 550: from 2 to 36, or if BASE is 0 then the leading characters are
! 551: used: `0x' for hex, `0' for octal, or decimal otherwise. Note
! 552: that this is done separately for the numerator and denominator, so
! 553: for instance `0xEF/100' is 239/100, whereas `0xEF/0x100' is
! 554: 239/256.
1.1.1.2 maekawa 555:
1.1.1.4 ! ohara 556: The return value is 0 if the entire string is a valid number, or
! 557: -1 if not.
1.1.1.2 maekawa 558:
1.1.1.4 ! ohara 559: - Function: void mpq_swap (mpq_t ROP1, mpq_t ROP2)
! 560: Swap the values ROP1 and ROP2 efficiently.
1.1.1.2 maekawa 561:
1.1.1.4 ! ohara 562:
! 563: File: gmp.info, Node: Rational Conversions, Next: Rational Arithmetic, Prev: Initializing Rationals, Up: Rational Number Functions
1.1.1.2 maekawa 564:
1.1.1.4 ! ohara 565: Conversion Functions
! 566: ====================
1.1.1.2 maekawa 567:
1.1.1.4 ! ohara 568: - Function: double mpq_get_d (mpq_t OP)
! 569: Convert OP to a `double'.
1.1.1.2 maekawa 570:
1.1.1.4 ! ohara 571: - Function: void mpq_set_d (mpq_t ROP, double OP)
! 572: - Function: void mpq_set_f (mpq_t ROP, mpf_t OP)
! 573: Set ROP to the value of OP, without rounding.
1.1.1.2 maekawa 574:
1.1.1.4 ! ohara 575: - Function: char * mpq_get_str (char *STR, int BASE, mpq_t OP)
! 576: Convert OP to a string of digits in base BASE. The base may vary
! 577: from 2 to 36. The string will be of the form `num/den', or if the
! 578: denominator is 1 then just `num'.
1.1.1.2 maekawa 579:
1.1.1.4 ! ohara 580: If STR is `NULL', the result string is allocated using the current
! 581: allocation function (*note Custom Allocation::). The block will be
! 582: `strlen(str)+1' bytes, that being exactly enough for the string and
! 583: null-terminator.
1.1.1.2 maekawa 584:
1.1.1.4 ! ohara 585: If STR is not `NULL', it should point to a block of storage large
! 586: enough for the result, that being
1.1.1.2 maekawa 587:
1.1.1.4 ! ohara 588: mpz_sizeinbase (mpq_numref(OP), BASE)
! 589: + mpz_sizeinbase (mpq_denref(OP), BASE) + 3
1.1.1.2 maekawa 590:
1.1.1.4 ! ohara 591: The three extra bytes are for a possible minus sign, possible
! 592: slash, and the null-terminator.
1.1.1.2 maekawa 593:
1.1.1.4 ! ohara 594: A pointer to the result string is returned, being either the
! 595: allocated block, or the given STR.
1.1.1.2 maekawa 596:
597:
1.1.1.4 ! ohara 598: File: gmp.info, Node: Rational Arithmetic, Next: Comparing Rationals, Prev: Rational Conversions, Up: Rational Number Functions
! 599:
! 600: Arithmetic Functions
! 601: ====================
! 602:
! 603: - Function: void mpq_add (mpq_t SUM, mpq_t ADDEND1, mpq_t ADDEND2)
! 604: Set SUM to ADDEND1 + ADDEND2.
! 605:
! 606: - Function: void mpq_sub (mpq_t DIFFERENCE, mpq_t MINUEND, mpq_t
! 607: SUBTRAHEND)
! 608: Set DIFFERENCE to MINUEND - SUBTRAHEND.
! 609:
! 610: - Function: void mpq_mul (mpq_t PRODUCT, mpq_t MULTIPLIER, mpq_t
! 611: MULTIPLICAND)
! 612: Set PRODUCT to MULTIPLIER times MULTIPLICAND.
1.1.1.2 maekawa 613:
1.1.1.4 ! ohara 614: - Function: void mpq_mul_2exp (mpq_t ROP, mpq_t OP1, unsigned long int
! 615: OP2)
! 616: Set ROP to OP1 times 2 raised to OP2.
1.1.1.2 maekawa 617:
1.1.1.4 ! ohara 618: - Function: void mpq_div (mpq_t QUOTIENT, mpq_t DIVIDEND, mpq_t
! 619: DIVISOR)
! 620: Set QUOTIENT to DIVIDEND/DIVISOR.
1.1.1.2 maekawa 621:
1.1.1.4 ! ohara 622: - Function: void mpq_div_2exp (mpq_t ROP, mpq_t OP1, unsigned long int
! 623: OP2)
! 624: Set ROP to OP1 divided by 2 raised to OP2.
1.1.1.2 maekawa 625:
1.1.1.4 ! ohara 626: - Function: void mpq_neg (mpq_t NEGATED_OPERAND, mpq_t OPERAND)
! 627: Set NEGATED_OPERAND to -OPERAND.
1.1.1.2 maekawa 628:
1.1.1.4 ! ohara 629: - Function: void mpq_abs (mpq_t ROP, mpq_t OP)
! 630: Set ROP to the absolute value of OP.
1.1.1.2 maekawa 631:
1.1.1.4 ! ohara 632: - Function: void mpq_inv (mpq_t INVERTED_NUMBER, mpq_t NUMBER)
! 633: Set INVERTED_NUMBER to 1/NUMBER. If the new denominator is zero,
! 634: this routine will divide by zero.
1.1.1.2 maekawa 635:
1.1.1.4 ! ohara 636:
! 637: File: gmp.info, Node: Comparing Rationals, Next: Applying Integer Functions, Prev: Rational Arithmetic, Up: Rational Number Functions
! 638:
! 639: Comparison Functions
! 640: ====================
! 641:
! 642: - Function: int mpq_cmp (mpq_t OP1, mpq_t OP2)
! 643: Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
! 644: if OP1 = OP2, and a negative value if OP1 < OP2.
1.1.1.2 maekawa 645:
1.1.1.4 ! ohara 646: To determine if two rationals are equal, `mpq_equal' is faster than
! 647: `mpq_cmp'.
1.1.1.2 maekawa 648:
1.1.1.4 ! ohara 649: - Macro: int mpq_cmp_ui (mpq_t OP1, unsigned long int NUM2, unsigned
! 650: long int DEN2)
! 651: - Macro: int mpq_cmp_si (mpq_t OP1, long int NUM2, unsigned long int
! 652: DEN2)
! 653: Compare OP1 and NUM2/DEN2. Return a positive value if OP1 >
! 654: NUM2/DEN2, zero if OP1 = NUM2/DEN2, and a negative value if OP1 <
! 655: NUM2/DEN2.
1.1.1.2 maekawa 656:
1.1.1.4 ! ohara 657: NUM2 and DEN2 are allowed to have common factors.
1.1.1.2 maekawa 658:
1.1.1.4 ! ohara 659: These functions are implemented as a macros and evaluate their
! 660: arguments multiple times.
1.1.1.2 maekawa 661:
1.1.1.4 ! ohara 662: - Macro: int mpq_sgn (mpq_t OP)
! 663: Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.
1.1.1.2 maekawa 664:
1.1.1.4 ! ohara 665: This function is actually implemented as a macro. It evaluates its
! 666: arguments multiple times.
! 667:
! 668: - Function: int mpq_equal (mpq_t OP1, mpq_t OP2)
! 669: Return non-zero if OP1 and OP2 are equal, zero if they are
! 670: non-equal. Although `mpq_cmp' can be used for the same purpose,
! 671: this function is much faster.
1.1.1.2 maekawa 672:
673:
1.1.1.4 ! ohara 674: File: gmp.info, Node: Applying Integer Functions, Next: I/O of Rationals, Prev: Comparing Rationals, Up: Rational Number Functions
! 675:
! 676: Applying Integer Functions to Rationals
! 677: =======================================
1.1.1.2 maekawa 678:
1.1.1.4 ! ohara 679: The set of `mpq' functions is quite small. In particular, there are
! 680: few functions for either input or output. The following functions give
! 681: direct access to the numerator and denominator of an `mpq_t'.
! 682:
! 683: Note that if an assignment to the numerator and/or denominator could
! 684: take an `mpq_t' out of the canonical form described at the start of
! 685: this chapter (*note Rational Number Functions::) then
! 686: `mpq_canonicalize' must be called before any other `mpq' functions are
! 687: applied to that `mpq_t'.
! 688:
! 689: - Macro: mpz_t mpq_numref (mpq_t OP)
! 690: - Macro: mpz_t mpq_denref (mpq_t OP)
! 691: Return a reference to the numerator and denominator of OP,
! 692: respectively. The `mpz' functions can be used on the result of
! 693: these macros.
! 694:
! 695: - Function: void mpq_get_num (mpz_t NUMERATOR, mpq_t RATIONAL)
! 696: - Function: void mpq_get_den (mpz_t DENOMINATOR, mpq_t RATIONAL)
! 697: - Function: void mpq_set_num (mpq_t RATIONAL, mpz_t NUMERATOR)
! 698: - Function: void mpq_set_den (mpq_t RATIONAL, mpz_t DENOMINATOR)
! 699: Get or set the numerator or denominator of a rational. These
! 700: functions are equivalent to calling `mpz_set' with an appropriate
! 701: `mpq_numref' or `mpq_denref'. Direct use of `mpq_numref' or
! 702: `mpq_denref' is recommended instead of these functions.
1.1.1.2 maekawa 703:
1.1.1.4 ! ohara 704:
! 705: File: gmp.info, Node: I/O of Rationals, Prev: Applying Integer Functions, Up: Rational Number Functions
1.1.1.2 maekawa 706:
1.1.1.4 ! ohara 707: Input and Output Functions
! 708: ==========================
1.1.1.2 maekawa 709:
1.1.1.4 ! ohara 710: When using any of these functions, it's a good idea to include
! 711: `stdio.h' before `gmp.h', since that will allow `gmp.h' to define
! 712: prototypes for these functions.
! 713:
! 714: Passing a `NULL' pointer for a STREAM argument to any of these
! 715: functions will make them read from `stdin' and write to `stdout',
! 716: respectively.
! 717:
! 718: - Function: size_t mpq_out_str (FILE *STREAM, int BASE, mpq_t OP)
! 719: Output OP on stdio stream STREAM, as a string of digits in base
! 720: BASE. The base may vary from 2 to 36. Output is in the form
! 721: `num/den' or if the denominator is 1 then just `num'.
! 722:
! 723: Return the number of bytes written, or if an error occurred,
! 724: return 0.
! 725:
! 726: - Function: size_t mpq_inp_str (mpq_t ROP, FILE *STREAM, int BASE)
! 727: Read a string of digits from STREAM and convert them to a rational
! 728: in ROP. Any initial white-space characters are read and
! 729: discarded. Return the number of characters read (including white
! 730: space), or 0 if a rational could not be read.
! 731:
! 732: The input can be a fraction like `17/63' or just an integer like
! 733: `123'. Reading stops at the first character not in this form, and
! 734: white space is not permitted within the string. If the input
! 735: might not be in canonical form, then `mpq_canonicalize' must be
! 736: called (*note Rational Number Functions::).
! 737:
! 738: The BASE can be between 2 and 36, or can be 0 in which case the
! 739: leading characters of the string determine the base, `0x' or `0X'
! 740: for hexadecimal, `0' for octal, or decimal otherwise. The leading
! 741: characters are examined separately for the numerator and
! 742: denominator of a fraction, so for instance `0x10/11' is 16/11,
! 743: whereas `0x10/0x11' is 16/17.
1.1.1.2 maekawa 744:
1.1.1.4 ! ohara 745:
! 746: File: gmp.info, Node: Floating-point Functions, Next: Low-level Functions, Prev: Rational Number Functions, Up: Top
1.1.1.2 maekawa 747:
1.1.1.4 ! ohara 748: Floating-point Functions
! 749: ************************
1.1.1.2 maekawa 750:
1.1.1.4 ! ohara 751: GMP floating point numbers are stored in objects of type `mpf_t' and
! 752: functions operating on them have an `mpf_' prefix.
1.1.1.2 maekawa 753:
1.1.1.4 ! ohara 754: The mantissa of each float has a user-selectable precision, limited
! 755: only by available memory. Each variable has its own precision, and
! 756: that can be increased or decreased at any time.
! 757:
! 758: The exponent of each float is a fixed precision, one machine word on
! 759: most systems. In the current implementation the exponent is a count of
! 760: limbs, so for example on a 32-bit system this means a range of roughly
! 761: 2^-68719476768 to 2^68719476736, or on a 64-bit system this will be
! 762: greater. Note however `mpf_get_str' can only return an exponent which
! 763: fits an `mp_exp_t' and currently `mpf_set_str' doesn't accept exponents
! 764: bigger than a `long'.
! 765:
! 766: Each variable keeps a size for the mantissa data actually in use.
! 767: This means that if a float is exactly represented in only a few bits
! 768: then only those bits will be used in a calculation, even if the
! 769: selected precision is high.
! 770:
! 771: All calculations are performed to the precision of the destination
! 772: variable. Each function is defined to calculate with "infinite
! 773: precision" followed by a truncation to the destination precision, but
! 774: of course the work done is only what's needed to determine a result
! 775: under that definition.
! 776:
! 777: The precision selected for a variable is a minimum value, GMP may
! 778: increase it a little to facilitate efficient calculation. Currently
! 779: this means rounding up to a whole limb, and then sometimes having a
! 780: further partial limb, depending on the high limb of the mantissa. But
! 781: applications shouldn't be concerned by such details.
! 782:
! 783: The mantissa in stored in binary, as might be imagined from the fact
! 784: precisions are expressed in bits. One consequence of this is that
! 785: decimal fractions like 0.1 cannot be represented exactly. The same is
! 786: true of plain IEEE `double' floats. This makes both highly unsuitable
! 787: for calculations involving money or other values that should be exact
! 788: decimal fractions. (Suitably scaled integers, or perhaps rationals,
! 789: are better choices.)
! 790:
! 791: `mpf' functions and variables have no special notion of infinity or
! 792: not-a-number, and applications must take care not to overflow the
! 793: exponent or results will be unpredictable. This might change in a
! 794: future release.
! 795:
! 796: Note that the `mpf' functions are _not_ intended as a smooth
! 797: extension to IEEE P754 arithmetic. In particular results obtained on
! 798: one computer often differ from the results on a computer with a
! 799: different word size.
1.1.1.2 maekawa 800:
1.1.1.4 ! ohara 801: * Menu:
1.1.1.2 maekawa 802:
1.1.1.4 ! ohara 803: * Initializing Floats::
! 804: * Assigning Floats::
! 805: * Simultaneous Float Init & Assign::
! 806: * Converting Floats::
! 807: * Float Arithmetic::
! 808: * Float Comparison::
! 809: * I/O of Floats::
! 810: * Miscellaneous Float Functions::
1.1.1.2 maekawa 811:
1.1.1.4 ! ohara 812:
! 813: File: gmp.info, Node: Initializing Floats, Next: Assigning Floats, Prev: Floating-point Functions, Up: Floating-point Functions
1.1.1.2 maekawa 814:
1.1.1.4 ! ohara 815: Initialization Functions
! 816: ========================
1.1.1.2 maekawa 817:
1.1.1.4 ! ohara 818: - Function: void mpf_set_default_prec (unsigned long int PREC)
! 819: Set the default precision to be *at least* PREC bits. All
! 820: subsequent calls to `mpf_init' will use this precision, but
! 821: previously initialized variables are unaffected.
! 822:
! 823: - Function: unsigned long int mpf_get_default_prec (void)
! 824: Return the default default precision actually used.
! 825:
! 826: An `mpf_t' object must be initialized before storing the first value
! 827: in it. The functions `mpf_init' and `mpf_init2' are used for that
! 828: purpose.
! 829:
! 830: - Function: void mpf_init (mpf_t X)
! 831: Initialize X to 0. Normally, a variable should be initialized
! 832: once only or at least be cleared, using `mpf_clear', between
! 833: initializations. The precision of X is undefined unless a default
! 834: precision has already been established by a call to
! 835: `mpf_set_default_prec'.
! 836:
! 837: - Function: void mpf_init2 (mpf_t X, unsigned long int PREC)
! 838: Initialize X to 0 and set its precision to be *at least* PREC
! 839: bits. Normally, a variable should be initialized once only or at
! 840: least be cleared, using `mpf_clear', between initializations.
! 841:
! 842: - Function: void mpf_clear (mpf_t X)
! 843: Free the space occupied by X. Make sure to call this function for
! 844: all `mpf_t' variables when you are done with them.
! 845:
! 846: Here is an example on how to initialize floating-point variables:
! 847: {
! 848: mpf_t x, y;
! 849: mpf_init (x); /* use default precision */
! 850: mpf_init2 (y, 256); /* precision _at least_ 256 bits */
! 851: ...
! 852: /* Unless the program is about to exit, do ... */
! 853: mpf_clear (x);
! 854: mpf_clear (y);
! 855: }
! 856:
! 857: The following three functions are useful for changing the precision
! 858: during a calculation. A typical use would be for adjusting the
! 859: precision gradually in iterative algorithms like Newton-Raphson, making
! 860: the computation precision closely match the actual accurate part of the
! 861: numbers.
1.1.1.2 maekawa 862:
1.1.1.4 ! ohara 863: - Function: unsigned long int mpf_get_prec (mpf_t OP)
! 864: Return the current precision of OP, in bits.
1.1.1.2 maekawa 865:
1.1.1.4 ! ohara 866: - Function: void mpf_set_prec (mpf_t ROP, unsigned long int PREC)
! 867: Set the precision of ROP to be *at least* PREC bits. The value in
! 868: ROP will be truncated to the new precision.
! 869:
! 870: This function requires a call to `realloc', and so should not be
! 871: used in a tight loop.
! 872:
! 873: - Function: void mpf_set_prec_raw (mpf_t ROP, unsigned long int PREC)
! 874: Set the precision of ROP to be *at least* PREC bits, without
! 875: changing the memory allocated.
! 876:
! 877: PREC must be no more than the allocated precision for ROP, that
! 878: being the precision when ROP was initialized, or in the most recent
! 879: `mpf_set_prec'.
! 880:
! 881: The value in ROP is unchanged, and in particular if it had a higher
! 882: precision than PREC it will retain that higher precision. New
! 883: values written to ROP will use the new PREC.
! 884:
! 885: Before calling `mpf_clear' or the full `mpf_set_prec', another
! 886: `mpf_set_prec_raw' call must be made to restore ROP to its original
! 887: allocated precision. Failing to do so will have unpredictable
! 888: results.
! 889:
! 890: `mpf_get_prec' can be used before `mpf_set_prec_raw' to get the
! 891: original allocated precision. After `mpf_set_prec_raw' it
! 892: reflects the PREC value set.
! 893:
! 894: `mpf_set_prec_raw' is an efficient way to use an `mpf_t' variable
! 895: at different precisions during a calculation, perhaps to gradually
! 896: increase precision in an iteration, or just to use various
! 897: different precisions for different purposes during a calculation.
1.1.1.2 maekawa 898:
1.1.1.4 ! ohara 899:
! 900: File: gmp.info, Node: Assigning Floats, Next: Simultaneous Float Init & Assign, Prev: Initializing Floats, Up: Floating-point Functions
1.1.1.2 maekawa 901:
1.1.1.4 ! ohara 902: Assignment Functions
! 903: ====================
1.1.1.2 maekawa 904:
1.1.1.4 ! ohara 905: These functions assign new values to already initialized floats
! 906: (*note Initializing Floats::).
1.1.1.2 maekawa 907:
1.1.1.4 ! ohara 908: - Function: void mpf_set (mpf_t ROP, mpf_t OP)
! 909: - Function: void mpf_set_ui (mpf_t ROP, unsigned long int OP)
! 910: - Function: void mpf_set_si (mpf_t ROP, signed long int OP)
! 911: - Function: void mpf_set_d (mpf_t ROP, double OP)
! 912: - Function: void mpf_set_z (mpf_t ROP, mpz_t OP)
! 913: - Function: void mpf_set_q (mpf_t ROP, mpq_t OP)
! 914: Set the value of ROP from OP.
! 915:
! 916: - Function: int mpf_set_str (mpf_t ROP, char *STR, int BASE)
! 917: Set the value of ROP from the string in STR. The string is of the
! 918: form `M@N' or, if the base is 10 or less, alternatively `MeN'.
! 919: `M' is the mantissa and `N' is the exponent. The mantissa is
! 920: always in the specified base. The exponent is either in the
! 921: specified base or, if BASE is negative, in decimal. The decimal
! 922: point expected is taken from the current locale, on systems
! 923: providing `localeconv'.
! 924:
! 925: The argument BASE may be in the ranges 2 to 36, or -36 to -2.
! 926: Negative values are used to specify that the exponent is in
! 927: decimal.
! 928:
! 929: Unlike the corresponding `mpz' function, the base will not be
! 930: determined from the leading characters of the string if BASE is 0.
! 931: This is so that numbers like `0.23' are not interpreted as octal.
! 932:
! 933: White space is allowed in the string, and is simply ignored.
! 934: [This is not really true; white-space is ignored in the beginning
! 935: of the string and within the mantissa, but not in other places,
! 936: such as after a minus sign or in the exponent. We are considering
! 937: changing the definition of this function, making it fail when
! 938: there is any white-space in the input, since that makes a lot of
! 939: sense. Please tell us your opinion about this change. Do you
! 940: really want it to accept "3 14" as meaning 314 as it does now?]
! 941:
! 942: This function returns 0 if the entire string is a valid number in
! 943: base BASE. Otherwise it returns -1.
! 944:
! 945: - Function: void mpf_swap (mpf_t ROP1, mpf_t ROP2)
! 946: Swap ROP1 and ROP2 efficiently. Both the values and the
! 947: precisions of the two variables are swapped.
1.1.1.2 maekawa 948:
1.1.1.4 ! ohara 949:
! 950: File: gmp.info, Node: Simultaneous Float Init & Assign, Next: Converting Floats, Prev: Assigning Floats, Up: Floating-point Functions
1.1.1.2 maekawa 951:
1.1.1.4 ! ohara 952: Combined Initialization and Assignment Functions
! 953: ================================================
1.1.1.2 maekawa 954:
1.1.1.4 ! ohara 955: For convenience, GMP provides a parallel series of
! 956: initialize-and-set functions which initialize the output and then store
! 957: the value there. These functions' names have the form `mpf_init_set...'
! 958:
! 959: Once the float has been initialized by any of the `mpf_init_set...'
! 960: functions, it can be used as the source or destination operand for the
! 961: ordinary float functions. Don't use an initialize-and-set function on
! 962: a variable already initialized!
! 963:
! 964: - Function: void mpf_init_set (mpf_t ROP, mpf_t OP)
! 965: - Function: void mpf_init_set_ui (mpf_t ROP, unsigned long int OP)
! 966: - Function: void mpf_init_set_si (mpf_t ROP, signed long int OP)
! 967: - Function: void mpf_init_set_d (mpf_t ROP, double OP)
! 968: Initialize ROP and set its value from OP.
! 969:
! 970: The precision of ROP will be taken from the active default
! 971: precision, as set by `mpf_set_default_prec'.
! 972:
! 973: - Function: int mpf_init_set_str (mpf_t ROP, char *STR, int BASE)
! 974: Initialize ROP and set its value from the string in STR. See
! 975: `mpf_set_str' above for details on the assignment operation.
1.1.1.2 maekawa 976:
1.1.1.4 ! ohara 977: Note that ROP is initialized even if an error occurs. (I.e., you
! 978: have to call `mpf_clear' for it.)
1.1.1.2 maekawa 979:
1.1.1.4 ! ohara 980: The precision of ROP will be taken from the active default
! 981: precision, as set by `mpf_set_default_prec'.
1.1.1.2 maekawa 982:
983:
1.1.1.4 ! ohara 984: File: gmp.info, Node: Converting Floats, Next: Float Arithmetic, Prev: Simultaneous Float Init & Assign, Up: Floating-point Functions
! 985:
! 986: Conversion Functions
! 987: ====================
! 988:
! 989: - Function: double mpf_get_d (mpf_t OP)
! 990: Convert OP to a `double'.
! 991:
! 992: - Function: double mpf_get_d_2exp (signed long int *EXP, mpf_t OP)
! 993: Find D and EXP such that D times 2 raised to EXP, with
! 994: 0.5<=abs(D)<1, is a good approximation to OP. This is similar to
! 995: the standard C function `frexp'.
! 996:
! 997: - Function: long mpf_get_si (mpf_t OP)
! 998: - Function: unsigned long mpf_get_ui (mpf_t OP)
! 999: Convert OP to a `long' or `unsigned long', truncating any fraction
! 1000: part. If OP is too big for the return type, the result is
! 1001: undefined.
1.1.1.2 maekawa 1002:
1.1.1.4 ! ohara 1003: See also `mpf_fits_slong_p' and `mpf_fits_ulong_p' (*note
! 1004: Miscellaneous Float Functions::).
1.1.1.2 maekawa 1005:
1.1.1.4 ! ohara 1006: - Function: char * mpf_get_str (char *STR, mp_exp_t *EXPPTR, int BASE,
! 1007: size_t N_DIGITS, mpf_t OP)
! 1008: Convert OP to a string of digits in base BASE. BASE can be 2 to
! 1009: 36. Up to N_DIGITS digits will be generated. Trailing zeros are
! 1010: not returned. No more digits than can be accurately represented
! 1011: by OP are ever generated. If N_DIGITS is 0 then that accurate
! 1012: maximum number of digits are generated.
! 1013:
! 1014: If STR is `NULL', the result string is allocated using the current
! 1015: allocation function (*note Custom Allocation::). The block will be
! 1016: `strlen(str)+1' bytes, that being exactly enough for the string and
! 1017: null-terminator.
! 1018:
! 1019: If STR is not `NULL', it should point to a block of N_DIGITS + 2
! 1020: bytes, that being enough for the mantissa, a possible minus sign,
! 1021: and a null-terminator. When N_DIGITS is 0 to get all significant
! 1022: digits, an application won't be able to know the space required,
! 1023: and STR should be `NULL' in that case.
! 1024:
! 1025: The generated string is a fraction, with an implicit radix point
! 1026: immediately to the left of the first digit. The applicable
! 1027: exponent is written through the EXPPTR pointer. For example, the
! 1028: number 3.1416 would be returned as string "31416" and exponent 1.
1.1.1.2 maekawa 1029:
1.1.1.4 ! ohara 1030: When OP is zero, an empty string is produced and the exponent
! 1031: returned is 0.
1.1.1.2 maekawa 1032:
1.1.1.4 ! ohara 1033: A pointer to the result string is returned, being either the
! 1034: allocated block or the given STR.
1.1.1.2 maekawa 1035:
1.1.1.4 ! ohara 1036:
! 1037: File: gmp.info, Node: Float Arithmetic, Next: Float Comparison, Prev: Converting Floats, Up: Floating-point Functions
1.1.1.2 maekawa 1038:
1.1.1.4 ! ohara 1039: Arithmetic Functions
! 1040: ====================
1.1.1.2 maekawa 1041:
1.1.1.4 ! ohara 1042: - Function: void mpf_add (mpf_t ROP, mpf_t OP1, mpf_t OP2)
! 1043: - Function: void mpf_add_ui (mpf_t ROP, mpf_t OP1, unsigned long int
! 1044: OP2)
! 1045: Set ROP to OP1 + OP2.
! 1046:
! 1047: - Function: void mpf_sub (mpf_t ROP, mpf_t OP1, mpf_t OP2)
! 1048: - Function: void mpf_ui_sub (mpf_t ROP, unsigned long int OP1, mpf_t
! 1049: OP2)
! 1050: - Function: void mpf_sub_ui (mpf_t ROP, mpf_t OP1, unsigned long int
! 1051: OP2)
! 1052: Set ROP to OP1 - OP2.
! 1053:
! 1054: - Function: void mpf_mul (mpf_t ROP, mpf_t OP1, mpf_t OP2)
! 1055: - Function: void mpf_mul_ui (mpf_t ROP, mpf_t OP1, unsigned long int
! 1056: OP2)
! 1057: Set ROP to OP1 times OP2.
! 1058:
! 1059: Division is undefined if the divisor is zero, and passing a zero
! 1060: divisor to the divide functions will make these functions intentionally
! 1061: divide by zero. This lets the user handle arithmetic exceptions in
! 1062: these functions in the same manner as other arithmetic exceptions.
! 1063:
! 1064: - Function: void mpf_div (mpf_t ROP, mpf_t OP1, mpf_t OP2)
! 1065: - Function: void mpf_ui_div (mpf_t ROP, unsigned long int OP1, mpf_t
! 1066: OP2)
! 1067: - Function: void mpf_div_ui (mpf_t ROP, mpf_t OP1, unsigned long int
! 1068: OP2)
! 1069: Set ROP to OP1/OP2.
! 1070:
! 1071: - Function: void mpf_sqrt (mpf_t ROP, mpf_t OP)
! 1072: - Function: void mpf_sqrt_ui (mpf_t ROP, unsigned long int OP)
! 1073: Set ROP to the square root of OP.
! 1074:
! 1075: - Function: void mpf_pow_ui (mpf_t ROP, mpf_t OP1, unsigned long int
! 1076: OP2)
! 1077: Set ROP to OP1 raised to the power OP2.
! 1078:
! 1079: - Function: void mpf_neg (mpf_t ROP, mpf_t OP)
! 1080: Set ROP to -OP.
! 1081:
! 1082: - Function: void mpf_abs (mpf_t ROP, mpf_t OP)
! 1083: Set ROP to the absolute value of OP.
! 1084:
! 1085: - Function: void mpf_mul_2exp (mpf_t ROP, mpf_t OP1, unsigned long int
! 1086: OP2)
! 1087: Set ROP to OP1 times 2 raised to OP2.
! 1088:
! 1089: - Function: void mpf_div_2exp (mpf_t ROP, mpf_t OP1, unsigned long int
! 1090: OP2)
! 1091: Set ROP to OP1 divided by 2 raised to OP2.
1.1.1.2 maekawa 1092:
1.1.1.4 ! ohara 1093:
! 1094: File: gmp.info, Node: Float Comparison, Next: I/O of Floats, Prev: Float Arithmetic, Up: Floating-point Functions
1.1.1.2 maekawa 1095:
1.1.1.4 ! ohara 1096: Comparison Functions
! 1097: ====================
1.1.1.2 maekawa 1098:
1.1.1.4 ! ohara 1099: - Function: int mpf_cmp (mpf_t OP1, mpf_t OP2)
! 1100: - Function: int mpf_cmp_d (mpf_t OP1, double OP2)
! 1101: - Function: int mpf_cmp_ui (mpf_t OP1, unsigned long int OP2)
! 1102: - Function: int mpf_cmp_si (mpf_t OP1, signed long int OP2)
! 1103: Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
! 1104: if OP1 = OP2, and a negative value if OP1 < OP2.
! 1105:
! 1106: - Function: int mpf_eq (mpf_t OP1, mpf_t OP2, unsigned long int op3)
! 1107: Return non-zero if the first OP3 bits of OP1 and OP2 are equal,
! 1108: zero otherwise. I.e., test of OP1 and OP2 are approximately equal.
! 1109:
! 1110: Caution: Currently only whole limbs are compared, and only in an
! 1111: exact fashion. In the future values like 1000 and 0111 may be
! 1112: considered the same to 3 bits (on the basis that their difference
! 1113: is that small).
! 1114:
! 1115: - Function: void mpf_reldiff (mpf_t ROP, mpf_t OP1, mpf_t OP2)
! 1116: Compute the relative difference between OP1 and OP2 and store the
! 1117: result in ROP. This is abs(OP1-OP2)/OP1.
1.1.1.2 maekawa 1118:
1.1.1.4 ! ohara 1119: - Macro: int mpf_sgn (mpf_t OP)
! 1120: Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.
! 1121:
! 1122: This function is actually implemented as a macro. It evaluates
! 1123: its arguments multiple times.
1.1.1.2 maekawa 1124:
1125:
1.1.1.4 ! ohara 1126: File: gmp.info, Node: I/O of Floats, Next: Miscellaneous Float Functions, Prev: Float Comparison, Up: Floating-point Functions
1.1.1.2 maekawa 1127:
1.1.1.4 ! ohara 1128: Input and Output Functions
! 1129: ==========================
1.1.1.2 maekawa 1130:
1.1.1.4 ! ohara 1131: Functions that perform input from a stdio stream, and functions that
! 1132: output to a stdio stream. Passing a `NULL' pointer for a STREAM
! 1133: argument to any of these functions will make them read from `stdin' and
! 1134: write to `stdout', respectively.
! 1135:
! 1136: When using any of these functions, it is a good idea to include
! 1137: `stdio.h' before `gmp.h', since that will allow `gmp.h' to define
! 1138: prototypes for these functions.
! 1139:
! 1140: - Function: size_t mpf_out_str (FILE *STREAM, int BASE, size_t
! 1141: N_DIGITS, mpf_t OP)
! 1142: Print OP to STREAM, as a string of digits. Return the number of
! 1143: bytes written, or if an error occurred, return 0.
! 1144:
! 1145: The mantissa is prefixed with an `0.' and is in the given BASE,
! 1146: which may vary from 2 to 36. An exponent then printed, separated
! 1147: by an `e', or if BASE is greater than 10 then by an `@'. The
! 1148: exponent is always in decimal. The decimal point follows the
! 1149: current locale, on systems providing `localeconv'.
! 1150:
! 1151: Up to N_DIGITS will be printed from the mantissa, except that no
! 1152: more digits than are accurately representable by OP will be
! 1153: printed. N_DIGITS can be 0 to select that accurate maximum.
! 1154:
! 1155: - Function: size_t mpf_inp_str (mpf_t ROP, FILE *STREAM, int BASE)
! 1156: Read a string in base BASE from STREAM, and put the read float in
! 1157: ROP. The string is of the form `M@N' or, if the base is 10 or
! 1158: less, alternatively `MeN'. `M' is the mantissa and `N' is the
! 1159: exponent. The mantissa is always in the specified base. The
! 1160: exponent is either in the specified base or, if BASE is negative,
! 1161: in decimal. The decimal point expected is taken from the current
! 1162: locale, on systems providing `localeconv'.
! 1163:
! 1164: The argument BASE may be in the ranges 2 to 36, or -36 to -2.
! 1165: Negative values are used to specify that the exponent is in
! 1166: decimal.
! 1167:
! 1168: Unlike the corresponding `mpz' function, the base will not be
! 1169: determined from the leading characters of the string if BASE is 0.
! 1170: This is so that numbers like `0.23' are not interpreted as octal.
1.1 maekawa 1171:
1.1.1.4 ! ohara 1172: Return the number of bytes read, or if an error occurred, return 0.
1.1 maekawa 1173:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to gmp.info-3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gmp