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