Annotation of OpenXM_contrib/gmp/gmp.info-1, Revision 1.1.1.1
1.1 maekawa 1: This is Info file gmp.info, produced by Makeinfo-1.64 from the input
2: file gmp.texi.
3:
4: START-INFO-DIR-ENTRY
5: * gmp: (gmp.info). GNU Multiple Precision Arithmetic Library.
6: END-INFO-DIR-ENTRY
7:
8: This file documents GNU MP, a library for arbitrary-precision
9: arithmetic.
10:
11: Copyright (C) 1991, 1993, 1994, 1995, 1996 Free Software Foundation,
12: Inc.
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:
29: File: gmp.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
30:
31: GNU MP
32: ******
33:
34: This manual documents how to install and use the GNU multiple
35: precision arithmetic library, version 2.0.2.
36:
37: * Menu:
38:
39: * Copying:: GMP Copying Conditions (LGPL).
40: * Introduction to MP:: Brief introduction to GNU MP.
41: * Installing MP:: How to configure and compile the MP library.
42: * MP Basics:: What every MP user should now.
43: * Reporting Bugs:: How to usefully report bugs.
44: * Integer Functions:: Functions for arithmetic on signed integers.
45: * Rational Number Functions:: Functions for arithmetic on rational numbers.
46: * Floating-point Functions:: Functions for arithmetic on floats.
47: * Low-level Functions:: Fast functions for natural numbers.
48: * BSD Compatible Functions:: All functions found in BSD MP.
49: * Custom Allocation:: How to customize the internal allocation.
50:
51: * Contributors::
52: * References::
53: * Concept Index::
54: * Function Index::
55:
56:
57: File: gmp.info, Node: Copying, Next: Introduction to MP, Prev: Top, Up: Top
58:
59: GNU MP Copying Conditions
60: *************************
61:
62: This library is "free"; this means that everyone is free to use it
63: and free to redistribute it on a free basis. The library is not in the
64: public domain; it is copyrighted and there are restrictions on its
65: distribution, but these restrictions are designed to permit everything
66: that a good cooperating citizen would want to do. What is not allowed
67: is to try to prevent others from further sharing any version of this
68: library that they might get from you.
69:
70: Specifically, we want to make sure that you have the right to give
71: away copies of the library, that you receive source code or else can
72: get it if you want it, that you can change this library or use pieces
73: of it in new free programs, and that you know you can do these things.
74:
75: To make sure that everyone has such rights, we have to forbid you to
76: deprive anyone else of these rights. For example, if you distribute
77: copies of the GNU MP library, you must give the recipients all the
78: rights that you have. You must make sure that they, too, receive or
79: can get the source code. And you must tell them their rights.
80:
81: Also, for our own protection, we must make certain that everyone
82: finds out that there is no warranty for the GNU MP library. If it is
83: modified by someone else and passed on, we want their recipients to
84: know that what they have is not what we distributed, so that any
85: problems introduced by others will not reflect on our reputation.
86:
87: The precise conditions of the license for the GNU MP library are
88: found in the Library General Public License that accompany the source
89: code.
90:
91:
92: File: gmp.info, Node: Introduction to MP, Next: Installing MP, Prev: Copying, Up: Top
93:
94: Introduction to GNU MP
95: **********************
96:
97: GNU MP is a portable library written in C for arbitrary precision
98: arithmetic on integers, rational numbers, and floating-point numbers.
99: It aims to provide the fastest possible arithmetic for all applications
100: that need higher precision than is directly supported by the basic C
101: types.
102:
103: Many applications use just a few hundred bits of precision; but some
104: applications may need thousands or even millions of bits. MP is
105: designed to give good performance for both, by choosing algorithms
106: based on the sizes of the operands, and by carefully keeping the
107: overhead at a minimum.
108:
109: The speed of MP is achieved by using fullwords as the basic
110: arithmetic type, by using sophisticated algorithms, by including
111: carefully optimized assembly code for the most common inner loops for
112: many different CPUs, and by a general emphasis on speed (as opposed to
113: simplicity or elegance).
114:
115: There is carefully optimized assembly code for these CPUs: DEC
116: Alpha, Amd 29000, HPPA 1.0 and 1.1, Intel Pentium and generic x86,
117: Intel i960, Motorola MC68000, MC68020, MC88100, and MC88110,
118: Motorola/IBM PowerPC, National NS32000, IBM POWER, MIPS R3000, R4000,
119: SPARCv7, SuperSPARC, generic SPARCv8, and DEC VAX. Some optimizations
120: also for ARM, Clipper, IBM ROMP (RT), and Pyramid AP/XP.
121:
122: This version of MP is released under a more liberal license than
123: previous versions. It is now permitted to link MP to non-free
124: programs, as long as MP source code is provided when distributing the
125: non-free program.
126:
127: How to use this Manual
128: ======================
129:
130: Everyone should read *Note MP Basics::. If you need to install the
131: library yourself, you need to read *Note Installing MP::, too.
132:
133: The rest of the manual can be used for later reference, although it
134: is probably a good idea to glance through it.
135:
136:
137: File: gmp.info, Node: Installing MP, Next: MP Basics, Prev: Introduction to MP, Up: Top
138:
139: Installing MP
140: *************
141:
142: To build MP, you first have to configure it for your CPU and
143: operating system. You need a C compiler, preferably GCC, but any
144: reasonable compiler should work. And you need a standard Unix `make'
145: program, plus some other standard Unix utility programs.
146:
147: (If you're on an MS-DOS machine, your can build MP using `make.bat'.
148: It requires that djgpp is installed. It does not require
149: configuration, nor is `make' needed; `make.bat' both configures and
150: builds the library.)
151:
152: Here are the steps needed to install the library on Unix systems:
153:
154: 1. In most cases, `./configure --target=cpu-vendor-os', should work
155: both for native and cross-compilation. If you get error messages,
156: your machine might not be supported.
157:
158: If you want to compile in a separate object directory, cd to that
159: directory, and prefix the configure command with the path to the
160: MP source directory. Not all `make' programs have the necessary
161: features to support this. In particular, SunOS and Slowaris
162: `make' have bugs that makes them unable to build from a separate
163: object directory. Use GNU `make' instead.
164:
165: In addition to the standard cpu-vendor-os tuples, MP recognizes
166: sparc8 and supersparc as valid CPU names. Specifying these CPU
167: names for relevant systems will improve performance significantly.
168:
169: In general, if you want a library that runs as fast as possible,
170: you should make sure you configure MP for the exact CPU type your
171: system uses.
172:
173: If you have `gcc' in your `PATH', it will be used by default. To
174: override this, pass `-with-gcc=no' to `configure'.
175:
176: 2. `make'
177:
178: This will compile MP, and create a library archive file `libgmp.a'
179: in the working directory.
180:
181: 3. `make check'
182:
183: This will make sure MP was built correctly. If you get error
184: messages, please report this to `bug-gmp@prep.ai.mit.edu'. (*Note
185: Reporting Bugs::, for information on what to include in useful bug
186: reports.)
187:
188: 4. `make install'
189:
190: This will copy the file `gmp.h' and `libgmp.a', as well as the info
191: files, to `/usr/local' (or if you passed the `--prefix' option to
192: `configure', to the directory given as argument to `--prefix').
193:
194: If you wish to build and install the BSD MP compatible functions, use
195: `make libmp.a' and `make install-bsdmp'.
196:
197: There are some other useful make targets:
198:
199: * `doc'
200:
201: Create a DVI version of the manual, in `gmp.dvi' and a set of info
202: files, in `gmp.info', `gmp.info-1', `gmp.info-2', etc.
203:
204: * `ps'
205:
206: Create a Postscript version of the manual, in `gmp.ps'.
207:
208: * `html'
209:
210: Create a HTML version of the manual, in `gmp.html'.
211:
212: * `clean'
213:
214: Delete all object files and archive files, but not the
215: configuration files.
216:
217: * `distclean'
218:
219: Delete all files not included in the distribution.
220:
221: * `uninstall'
222:
223: Delete all files copied by `make install'.
224:
225: Known Build Problems
226: ====================
227:
228: GCC 2.7.2 (as well as 2.6.3) for the RS/6000 and PowerPC can not be
229: used to compile MP, due to a bug in GCC. If you want to use GCC for
230: these machines, you need to apply the patch below to GCC, or use a
231: later version of the compiler.
232:
233: If you are on a Sequent Symmetry, use the GNU assembler instead of
234: the system's assembler, since the latter has serious bugs.
235:
236: The system compiler on NeXT is a massacred and old gcc, even if the
237: compiler calls itself `cc'. This compiler cannot be used to build MP.
238: You need to get a real gcc, and install that before you compile MP.
239: (NeXT might have fixed this in newer releases of their system.)
240:
241: The system C compiler under SunOS 4 has a bug that makes it
242: miscompile mpq/get_d.c. This will make `make check' fail.
243:
244: Please report other problems to `bug-gmp@prep.ai.mit.edu'. *Note
245: Reporting Bugs::.
246:
247: Patch to apply to GCC 2.6.3 and 2.7.2:
248:
249: *** config/rs6000/rs6000.md Sun Feb 11 08:22:11 1996
250: --- config/rs6000/rs6000.md.new Sun Feb 18 03:33:37 1996
251: ***************
252: *** 920,926 ****
253: (set (match_operand:SI 0 "gpc_reg_operand" "=r")
254: (not:SI (match_dup 1)))]
255: ""
256: ! "nor. %0,%2,%1"
257: [(set_attr "type" "compare")])
258:
259: (define_insn ""
260: --- 920,926 ----
261: (set (match_operand:SI 0 "gpc_reg_operand" "=r")
262: (not:SI (match_dup 1)))]
263: ""
264: ! "nor. %0,%1,%1"
265: [(set_attr "type" "compare")])
266:
267: (define_insn ""
268:
269:
270: File: gmp.info, Node: MP Basics, Next: Reporting Bugs, Prev: Installing MP, Up: Top
271:
272: MP Basics
273: *********
274:
275: All declarations needed to use MP are collected in the include file
276: `gmp.h'. It is designed to work with both C and C++ compilers.
277:
278: Nomenclature and Types
279: ======================
280:
281: In this manual, "integer" usually means a multiple precision integer, as
282: defined by the MP library. The C data type for such integers is
283: `mpz_t'. Here are some examples of how to declare such integers:
284:
285: mpz_t sum;
286:
287: struct foo { mpz_t x, y; };
288:
289: mpz_t vec[20];
290:
291: "Rational number" means a multiple precision fraction. The C data type
292: for these fractions is `mpq_t'. For example:
293:
294: mpq_t quotient;
295:
296: "Floating point number" or "Float" for short, is an arbitrary precision
297: mantissa with an limited precision exponent. The C data type for such
298: objects is `mpf_t'.
299:
300: A "limb" means the part of a multi-precision number that fits in a
301: single word. (We chose this word because a limb of the human body is
302: analogous to a digit, only larger, and containing several digits.)
303: Normally a limb contains 32 or 64 bits. The C data type for a limb is
304: `mp_limb_t'.
305:
306: Function Classes
307: ================
308:
309: There are six classes of functions in the MP library:
310:
311: 1. Functions for signed integer arithmetic, with names beginning with
312: `mpz_'. The associated type is `mpz_t'. There are about 100
313: functions in this class.
314:
315: 2. Functions for rational number arithmetic, with names beginning with
316: `mpq_'. The associated type is `mpq_t'. There are about 20
317: functions in this class, but the functions in the previous class
318: can be used for performing arithmetic on the numerator and
319: denominator separately.
320:
321: 3. Functions for floating-point arithmetic, with names beginning with
322: `mpf_'. The associated type is `mpf_t'. There are about 50
323: functions is this class.
324:
325: 4. Functions compatible with Berkeley MP, such as `itom', `madd', and
326: `mult'. The associated type is `MINT'.
327:
328: 5. Fast low-level functions that operate on natural numbers. These
329: are used by the functions in the preceding groups, and you can
330: also call them directly from very time-critical user programs.
331: These functions' names begin with `mpn_'. There are about 30
332: (hard-to-use) functions in this class.
333:
334: The associated type is array of `mp_limb_t'.
335:
336: 6. Miscellaneous functions. Functions for setting up custom
337: allocation.
338:
339: MP Variable Conventions
340: =======================
341:
342: As a general rule, all MP functions expect output arguments before
343: input arguments. This notation is based on an analogy with the
344: assignment operator. (The BSD MP compatibility functions disobey this
345: rule, having the output argument(s) last.)
346:
347: MP allows you to use the same variable for both input and output in
348: the same expression. For example, the main function for integer
349: multiplication, `mpz_mul', can be used like this: `mpz_mul (x, x, x)'.
350: This computes the square of X and puts the result back in X.
351:
352: Before you can assign to an MP variable, you need to initialize it
353: by calling one of the special initialization functions. When you're
354: done with a variable, you need to clear it out, using one of the
355: functions for that purpose. Which function to use depends on the type
356: of variable. See the chapters on integer functions, rational number
357: functions, and floating-point functions for details.
358:
359: A variable should only be initialized once, or at least cleared out
360: between each initialization. After a variable has been initialized, it
361: may be assigned to any number of times.
362:
363: For efficiency reasons, avoid to initialize and clear out a variable
364: in loops. Instead, initialize it before entering the loop, and clear
365: it out after the loop has exited.
366:
367: You don't need to be concerned about allocating additional space for
368: MP variables. All functions in MP automatically allocate additional
369: space when a variable does not already have enough space. They do not,
370: however, reduce the space when a smaller number is stored in the
371: object. Most of the time, this policy is best, since it avoids
372: frequent re-allocation.
373:
374: Useful Macros and Constants
375: ===========================
376:
377: - Global Constant: const int mp_bits_per_limb
378: The number of bits per limb.
379:
380: - Macro: __GNU_MP_VERSION
381: - Macro: __GNU_MP_VERSION_MINOR
382: The major and minor MP version, respectively, as integers.
383:
384: Compatibility with Version 1.x
385: ==============================
386:
387: This version of MP is upward compatible with previous versions of
388: MP, with a few exceptions.
389:
390: 1. Integer division functions round the result differently. The old
391: functions (`mpz_div', `mpz_divmod', `mpz_mdiv', `mpz_mdivmod',
392: etc) now all use floor rounding (i.e., they round the quotient to
393: -infinity). There are a lot of new functions for integer
394: division, giving the user better control over the rounding.
395:
396: 2. The function `mpz_mod' now compute the true *mod* function.
397:
398: 3. The functions `mpz_powm' and `mpz_powm_ui' now use *mod* for
399: reduction.
400:
401: 4. The assignment functions for rational numbers do no longer
402: canonicalize their results. In the case a non-canonical result
403: could arise from an assignment, the user need to insert an
404: explicit call to `mpq_canonicalize'. This change was made for
405: efficiency.
406:
407: 5. Output generated by `mpz_out_raw' in this release cannot be read
408: by `mpz_inp_raw' in previous releases. This change was made for
409: making the file format truly portable between machines with
410: different word sizes.
411:
412: 6. Several `mpn' functions have changed. But they were intentionally
413: undocumented in previous releases.
414:
415: 7. The functions `mpz_cmp_ui', `mpz_cmp_si', and `mpq_cmp_ui' are now
416: implementated as macros, and thereby sometimes evaluate their
417: arguments multiple times.
418:
419: 8. The functions `mpz_pow_ui' and `mpz_ui_pow_ui' now yield 1 for
420: 0^0. (In version 1, they yielded 0.)
421:
422:
423: Getting the Latest Version of MP
424: ================================
425:
426: The latest version of the MP library is available by anonymous ftp
427: from from `prep.ai.mit.edu'. The file name is
428: `/pub/gnu/gmp-M.N.tar.gz'. Many sites around the world mirror `prep';
429: please use a mirror site near you.
430:
431:
432: File: gmp.info, Node: Reporting Bugs, Next: Integer Functions, Prev: MP Basics, Up: Top
433:
434: Reporting Bugs
435: **************
436:
437: If you think you have found a bug in the MP library, please
438: investigate it and report it. We have made this library available to
439: you, and it is not to ask too much from you, to ask you to report the
440: bugs that you find.
441:
442: There are a few things you should think about when you put your bug
443: report together.
444:
445: You have to send us a test case that makes it possible for us to
446: reproduce the bug. Include instructions on how to run the test case.
447:
448: You also have to explain what is wrong; if you get a crash, or if
449: the results printed are incorrect and in that case, in what way.
450:
451: It is not uncommon that an observed problem is actually due to a bug
452: in the compiler used when building MP; the MP code tends to explore
453: interesting corners in compilers. Therefore, please include compiler
454: version information in your bug report. This can be extracted using
455: `what `which cc`', or, if you're using gcc, `gcc -v'. Also, include
456: the output from `uname -a'.
457:
458: If your bug report is good, we will do our best to help you to get a
459: corrected version of the library; if the bug report is poor, we won't
460: do anything about it (aside of chiding you to send better bug reports).
461:
462: Send your bug report to: `bug-gmp@prep.ai.mit.edu'.
463:
464: If you think something in this manual is unclear, or downright
465: incorrect, or if the language needs to be improved, please send a note
466: to the same address.
467:
468:
469: File: gmp.info, Node: Integer Functions, Next: Rational Number Functions, Prev: Reporting Bugs, Up: Top
470:
471: Integer Functions
472: *****************
473:
474: This chapter describes the MP functions for performing integer
475: arithmetic. These functions start with the prefix `mpz_'.
476:
477: Arbitrary precision integers are stored in objects of type `mpz_t'.
478:
479: * Menu:
480:
481: * Initializing Integers::
482: * Assigning Integers::
483: * Simultaneous Integer Init & Assign::
484: * Converting Integers::
485: * Integer Arithmetic::
486: * Comparison Functions::
487: * Integer Logic and Bit Fiddling::
488: * I/O of Integers::
489: * Miscellaneous Integer Functions::
490:
491:
492: File: gmp.info, Node: Initializing Integers, Next: Assigning Integers, Up: Integer Functions
493:
494: Initialization and Assignment Functions
495: =======================================
496:
497: The functions for integer arithmetic assume that all integer objects
498: are initialized. You do that by calling the function `mpz_init'.
499:
500: - Function: void mpz_init (mpz_t INTEGER)
501: Initialize INTEGER with limb space and set the initial numeric
502: value to 0. Each variable should normally only be initialized
503: once, or at least cleared out (using `mpz_clear') between each
504: initialization.
505:
506: Here is an example of using `mpz_init':
507:
508: {
509: mpz_t integ;
510: mpz_init (integ);
511: ...
512: mpz_add (integ, ...);
513: ...
514: mpz_sub (integ, ...);
515:
516: /* Unless the program is about to exit, do ... */
517: mpz_clear (integ);
518: }
519:
520: As you can see, you can store new values any number of times, once an
521: object is initialized.
522:
523: - Function: void mpz_clear (mpz_t INTEGER)
524: Free the limb space occupied by INTEGER. Make sure to call this
525: function for all `mpz_t' variables when you are done with them.
526:
527: - Function: void * _mpz_realloc (mpz_t INTEGER, mp_size_t NEW_ALLOC)
528: Change the limb space allocation to NEW_ALLOC limbs. This
529: function is not normally called from user code, but it can be used
530: to give memory back to the heap, or to increase the space of a
531: variable to avoid repeated automatic re-allocation.
532:
533: - Function: void mpz_array_init (mpz_t INTEGER_ARRAY[], size_t
534: ARRAY_SIZE, mp_size_t FIXED_NUM_BITS)
535: Allocate *fixed* limb space for all ARRAY_SIZE integers in
536: INTEGER_ARRAY. The fixed allocation for each integer in the array
537: is enough to store FIXED_NUM_BITS. If the fixed space will be
538: insufficient for storing the result of a subsequent calculation,
539: the result is unpredictable.
540:
541: This function is useful for decreasing the working set for some
542: algorithms that use large integer arrays.
543:
544: There is no way to de-allocate the storage allocated by this
545: function. Don't call `mpz_clear'!
546:
547:
548: File: gmp.info, Node: Assigning Integers, Next: Simultaneous Integer Init & Assign, Prev: Initializing Integers, Up: Integer Functions
549:
550: Assignment Functions
551: --------------------
552:
553: These functions assign new values to already initialized integers
554: (*note Initializing Integers::.).
555:
556: - Function: void mpz_set (mpz_t ROP, mpz_t OP)
557: - Function: void mpz_set_ui (mpz_t ROP, unsigned long int OP)
558: - Function: void mpz_set_si (mpz_t ROP, signed long int OP)
559: - Function: void mpz_set_d (mpz_t ROP, double OP)
560: - Function: void mpz_set_q (mpz_t ROP, mpq_t OP)
561: - Function: void mpz_set_f (mpz_t ROP, mpf_t OP)
562: Set the value of ROP from OP.
563:
564: - Function: int mpz_set_str (mpz_t ROP, char *STR, int BASE)
565: Set the value of ROP from STR, a '\0'-terminated C string in base
566: BASE. White space is allowed in the string, and is simply
567: ignored. The base may vary from 2 to 36. If BASE is 0, the
568: actual base is determined from the leading characters: if the
569: first two characters are `0x' or `0X', hexadecimal is assumed,
570: otherwise if the first character is `0', octal is assumed,
571: otherwise decimal is assumed.
572:
573: This function returns 0 if the entire string up to the '\0' is a
574: valid number in base BASE. Otherwise it returns -1.
575:
576:
577: File: gmp.info, Node: Simultaneous Integer Init & Assign, Next: Converting Integers, Prev: Assigning Integers, Up: Integer Functions
578:
579: Combined Initialization and Assignment Functions
580: ------------------------------------------------
581:
582: For convenience, MP provides a parallel series of initialize-and-set
583: functions which initialize the output and then store the value there.
584: These functions' names have the form `mpz_init_set...'
585:
586: Here is an example of using one:
587:
588: {
589: mpz_t pie;
590: mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10);
591: ...
592: mpz_sub (pie, ...);
593: ...
594: mpz_clear (pie);
595: }
596:
597: Once the integer has been initialized by any of the `mpz_init_set...'
598: functions, it can be used as the source or destination operand for the
599: ordinary integer functions. Don't use an initialize-and-set function
600: on a variable already initialized!
601:
602: - Function: void mpz_init_set (mpz_t ROP, mpz_t OP)
603: - Function: void mpz_init_set_ui (mpz_t ROP, unsigned long int OP)
604: - Function: void mpz_init_set_si (mpz_t ROP, signed long int OP)
605: - Function: void mpz_init_set_d (mpz_t ROP, double OP)
606: Initialize ROP with limb space and set the initial numeric value
607: from OP.
608:
609: - Function: int mpz_init_set_str (mpz_t ROP, char *STR, int BASE)
610: Initialize ROP and set its value like `mpz_set_str' (see its
611: documentation above for details).
612:
613: If the string is a correct base BASE number, the function returns
614: 0; if an error occurs it returns -1. ROP is initialized even if
615: an error occurs. (I.e., you have to call `mpz_clear' for it.)
616:
617:
618: File: gmp.info, Node: Converting Integers, Next: Integer Arithmetic, Prev: Simultaneous Integer Init & Assign, Up: Integer Functions
619:
620: Conversion Functions
621: ====================
622:
623: This section describes functions for converting arbitrary precision
624: integers to standard C types. Functions for converting *to* arbitrary
625: precision integers are described in *Note Assigning Integers:: and
626: *Note I/O of Integers::.
627:
628: - Function: unsigned long int mpz_get_ui (mpz_t OP)
629: Return the least significant part from OP. This function combined
630: with
631: `mpz_tdiv_q_2exp(..., OP, CHAR_BIT*sizeof(unsigned long int))' can
632: be used to extract the limbs of an integer.
633:
634: - Function: signed long int mpz_get_si (mpz_t OP)
635: If OP fits into a `signed long int' return the value of OP.
636: Otherwise return the least significant part of OP, with the same
637: sign as OP.
638:
639: If OP is too large to fit in a `signed long int', the returned
640: result is probably not very useful.
641:
642: - Function: double mpz_get_d (mpz_t OP)
643: Convert OP to a double.
644:
645: - Function: char * mpz_get_str (char *STR, int BASE, mpz_t OP)
646: Convert OP to a string of digits in base BASE. The base may vary
647: from 2 to 36.
648:
649: If STR is NULL, space for the result string is allocated using the
650: default allocation function, and a pointer to the string is
651: returned.
652:
653: If STR is not NULL, it should point to a block of storage enough
654: large for the result. To find out the right amount of space to
655: provide for STR, use `mpz_sizeinbase (OP, BASE) + 2'. The two
656: extra bytes are for a possible minus sign, and for the terminating
657: null character.
658:
659:
660: File: gmp.info, Node: Integer Arithmetic, Next: Comparison Functions, Prev: Converting Integers, Up: Integer Functions
661:
662: Arithmetic Functions
663: ====================
664:
665: - Function: void mpz_add (mpz_t ROP, mpz_t OP1, mpz_t OP2)
666: - Function: void mpz_add_ui (mpz_t ROP, mpz_t OP1, unsigned long int
667: OP2)
668: Set ROP to OP1 + OP2.
669:
670: - Function: void mpz_sub (mpz_t ROP, mpz_t OP1, mpz_t OP2)
671: - Function: void mpz_sub_ui (mpz_t ROP, mpz_t OP1, unsigned long int
672: OP2)
673: Set ROP to OP1 - OP2.
674:
675: - Function: void mpz_mul (mpz_t ROP, mpz_t OP1, mpz_t OP2)
676: - Function: void mpz_mul_ui (mpz_t ROP, mpz_t OP1, unsigned long int
677: OP2)
678: Set ROP to OP1 times OP2.
679:
680: - Function: void mpz_mul_2exp (mpz_t ROP, mpz_t OP1, unsigned long int
681: OP2)
682: Set ROP to OP1 times 2 raised to OP2. This operation can also be
683: defined as a left shift, OP2 steps.
684:
685: - Function: void mpz_neg (mpz_t ROP, mpz_t OP)
686: Set ROP to -OP.
687:
688: - Function: void mpz_abs (mpz_t ROP, mpz_t OP)
689: Set ROP to the absolute value of OP.
690:
691: - Function: void mpz_fac_ui (mpz_t ROP, unsigned long int OP)
692: Set ROP to OP!, the factorial of OP.
693:
694: Division functions
695: ------------------
696:
697: Division is undefined if the divisor is zero, and passing a zero
698: divisor to the divide or modulo functions, as well passing a zero mod
699: argument to the `mpz_powm' and `mpz_powm_ui' functions, will make these
700: functions intentionally divide by zero. This gives the user the
701: possibility to handle arithmetic exceptions in these functions in the
702: same manner as other arithmetic exceptions.
703:
704: There are three main groups of division functions:
705: * Functions that truncate the quotient towards 0. The names of these
706: functions start with `mpz_tdiv'. The `t' in the name is short for
707: `truncate'.
708:
709: * Functions that round the quotient towards -infinity. The names of
710: these routines start with `mpz_fdiv'. The `f' in the name is
711: short for `floor'.
712:
713: * Functions that round the quotient towards +infinity. The names of
714: these routines start with `mpz_cdiv'. The `c' in the name is
715: short for `ceil'.
716:
717: For each rounding mode, there are a couple of variants. Here `q'
718: means that the quotient is computed, while `r' means that the remainder
719: is computed. Functions that compute both the quotient and remainder
720: have `qr' in the name.
721:
722: - Function: void mpz_tdiv_q (mpz_t ROP, mpz_t OP1, mpz_t OP2)
723: - Function: void mpz_tdiv_q_ui (mpz_t ROP, mpz_t OP1, unsigned long
724: int OP2)
725: Set ROP to [OP1/OP2]. The quotient is truncated towards 0.
726:
727: - Function: void mpz_tdiv_r (mpz_t ROP, mpz_t OP1, mpz_t OP2)
728: - Function: void mpz_tdiv_r_ui (mpz_t ROP, mpz_t OP1, unsigned long
729: int OP2)
730: Set ROP to (OP1 - [OP1/OP2] * OP2). Unless the remainder is zero,
731: it has the same sign as the dividend.
732:
733: - Function: void mpz_tdiv_qr (mpz_t ROP1, mpz_t ROP2, mpz_t OP1, mpz_t
734: OP2)
735: - Function: void mpz_tdiv_qr_ui (mpz_t ROP1, mpz_t ROP2, mpz_t OP1,
736: unsigned long int OP2)
737: Divide OP1 by OP2 and put the quotient in ROP1 and the remainder
738: in ROP2. The quotient is rounded towards 0. Unless the remainder
739: is zero, it has the same sign as the dividend.
740:
741: If ROP1 and ROP2 are the same variable, the results are undefined.
742:
743: - Function: void mpz_fdiv_q (mpz_t ROP1, mpz_t OP1, mpz_t OP2)
744: - Function: void mpz_fdiv_q_ui (mpz_t ROP, mpz_t OP1, unsigned long
745: int OP2)
746: Set ROP to OP1/OP2. The quotient is rounded towards -infinity.
747:
748: - Function: void mpz_fdiv_r (mpz_t ROP, mpz_t OP1, mpz_t OP2)
749: - Function: unsigned long int mpz_fdiv_r_ui (mpz_t ROP, mpz_t OP1,
750: unsigned long int OP2)
751: Divide OP1 by OP2 and put the remainder in ROP. Unless the
752: remainder is zero, it has the same sign as the divisor.
753:
754: For `mpz_fdiv_r_ui' the remainder is small enough to fit in an
755: `unsigned long int', and is therefore returned.
756:
757: - Function: void mpz_fdiv_qr (mpz_t ROP1, mpz_t ROP2, mpz_t OP1, mpz_t
758: OP2)
759: - Function: unsigned long int mpz_fdiv_qr_ui (mpz_t ROP1, mpz_t ROP2,
760: mpz_t OP1, unsigned long int OP2)
761: Divide OP1 by OP2 and put the quotient in ROP1 and the remainder
762: in ROP2. The quotient is rounded towards -infinity. Unless the
763: remainder is zero, it has the same sign as the divisor.
764:
765: For `mpz_fdiv_qr_ui' the remainder is small enough to fit in an
766: `unsigned long int', and is therefore returned.
767:
768: If ROP1 and ROP2 are the same variable, the results are undefined.
769:
770: - Function: unsigned long int mpz_fdiv_ui (mpz_t OP1, unsigned long
771: int OP2)
772: This function is similar to `mpz_fdiv_r_ui', but the remainder is
773: only returned; it is not stored anywhere.
774:
775: - Function: void mpz_cdiv_q (mpz_t ROP1, mpz_t OP1, mpz_t OP2)
776: - Function: void mpz_cdiv_q_ui (mpz_t ROP, mpz_t OP1, unsigned long
777: int OP2)
778: Set ROP to OP1/OP2. The quotient is rounded towards +infinity.
779:
780: - Function: void mpz_cdiv_r (mpz_t ROP, mpz_t OP1, mpz_t OP2)
781: - Function: unsigned long int mpz_cdiv_r_ui (mpz_t ROP, mpz_t OP1,
782: unsigned long int OP2)
783: Divide OP1 by OP2 and put the remainder in ROP. Unless the
784: remainder is zero, it has the opposite sign as the divisor.
785:
786: For `mpz_cdiv_r_ui' the negated remainder is small enough to fit
787: in an `unsigned long int', and it is therefore returned.
788:
789: - Function: void mpz_cdiv_qr (mpz_t ROP1, mpz_t ROP2, mpz_t OP1, mpz_t
790: OP2)
791: - Function: unsigned long int mpz_cdiv_qr_ui (mpz_t ROP1, mpz_t ROP2,
792: mpz_t OP1, unsigned long int OP2)
793: Divide OP1 by OP2 and put the quotient in ROP1 and the remainder
794: in ROP2. The quotient is rounded towards +infinity. Unless the
795: remainder is zero, it has the opposite sign as the divisor.
796:
797: For `mpz_cdiv_qr_ui' the negated remainder is small enough to fit
798: in an `unsigned long int', and it is therefore returned.
799:
800: If ROP1 and ROP2 are the same variable, the results are undefined.
801:
802: - Function: unsigned long int mpz_cdiv_ui (mpz_t OP1, unsigned long
803: int OP2)
804: Return the negated remainder, similar to `mpz_cdiv_r_ui'. (The
805: difference is that this function doesn't store the remainder
806: anywhere.)
807:
808: - Function: void mpz_mod (mpz_t ROP, mpz_t OP1, mpz_t OP2)
809: - Function: unsigned long int mpz_mod_ui (mpz_t ROP, mpz_t OP1,
810: unsigned long int OP2)
811: Set ROP to OP1 `mod' OP2. The sign of the divisor is ignored, and
812: the result is always non-negative.
813:
814: For `mpz_mod_ui' the remainder is small enough to fit in an
815: `unsigned long int', and is therefore returned.
816:
817: - Function: void mpz_divexact (mpz_t ROP, mpz_t OP1, mpz_t OP2)
818: Set ROP to OP1/OP2. This function produces correct results only
819: when it is known in advance that OP2 divides OP1.
820:
821: Since mpz_divexact is much faster than any of the other routines
822: that produce the quotient (*note References::. Jebelean), it is
823: the best choice for instances in which exact division is known to
824: occur, such as reducing a rational to lowest terms.
825:
826: - Function: void mpz_tdiv_q_2exp (mpz_t ROP, mpz_t OP1, unsigned long
827: int OP2)
828: Set ROP to OP1 divided by 2 raised to OP2. The quotient is
829: rounded towards 0.
830:
831: - Function: void mpz_tdiv_r_2exp (mpz_t ROP, mpz_t OP1, unsigned long
832: int OP2)
833: Divide OP1 by (2 raised to OP2) and put the remainder in ROP.
834: Unless it is zero, ROP will have the same sign as OP1.
835:
836: - Function: void mpz_fdiv_q_2exp (mpz_t ROP, mpz_t OP1, unsigned long
837: int OP2)
838: Set ROP to OP1 divided by 2 raised to OP2. The quotient is
839: rounded towards -infinity.
840:
841: - Function: void mpz_fdiv_r_2exp (mpz_t ROP, mpz_t OP1, unsigned long
842: int OP2)
843: Divide OP1 by (2 raised to OP2) and put the remainder in ROP. The
844: sign of ROP will always be positive.
845:
846: This operation can also be defined as masking of the OP2 least
847: significant bits.
848:
849: Exponentialization Functions
850: ----------------------------
851:
852: - Function: void mpz_powm (mpz_t ROP, mpz_t BASE, mpz_t EXP, mpz_t MOD)
853: - Function: void mpz_powm_ui (mpz_t ROP, mpz_t BASE, unsigned long int
854: EXP, mpz_t MOD)
855: Set ROP to (BASE raised to EXP) `mod' MOD. If EXP is negative,
856: the result is undefined.
857:
858: - Function: void mpz_pow_ui (mpz_t ROP, mpz_t BASE, unsigned long int
859: EXP)
860: - Function: void mpz_ui_pow_ui (mpz_t ROP, unsigned long int BASE,
861: unsigned long int EXP)
862: Set ROP to BASE raised to EXP. The case of 0^0 yields 1.
863:
864: Square Root Functions
865: ---------------------
866:
867: - Function: void mpz_sqrt (mpz_t ROP, mpz_t OP)
868: Set ROP to the truncated integer part of the square root of OP.
869:
870: - Function: void mpz_sqrtrem (mpz_t ROP1, mpz_t ROP2, mpz_t OP)
871: Set ROP1 to the truncated integer part of the square root of OP,
872: like `mpz_sqrt'. Set ROP2 to OP-ROP1*ROP1, (i.e., zero if OP is a
873: perfect square).
874:
875: If ROP1 and ROP2 are the same variable, the results are undefined.
876:
877: - Function: int mpz_perfect_square_p (mpz_t OP)
878: Return non-zero if OP is a perfect square, i.e., if the square
879: root of OP is an integer. Return zero otherwise.
880:
881: Number Theoretic Functions
882: --------------------------
883:
884: - Function: int mpz_probab_prime_p (mpz_t OP, int REPS)
885: If this function returns 0, OP is definitely not prime. If it
886: returns 1, then OP is `probably' prime. The probability of a
887: false positive is (1/4)**REPS. A reasonable value of reps is 25.
888:
889: An implementation of the probabilistic primality test found in
890: Seminumerical Algorithms (*note References::. Knuth).
891:
892: - Function: void mpz_gcd (mpz_t ROP, mpz_t OP1, mpz_t OP2)
893: Set ROP to the greatest common divisor of OP1 and OP2.
894:
895: - Function: unsigned long int mpz_gcd_ui (mpz_t ROP, mpz_t OP1,
896: unsigned long int OP2)
897: Compute the greatest common divisor of OP1 and OP2. If ROP is not
898: NULL, store the result there.
899:
900: If the result is small enough to fit in an `unsigned long int', it
901: is returned. If the result does not fit, 0 is returned, and the
902: result is equal to the argument OP1. Note that the result will
903: always fit if OP2 is non-zero.
904:
905: - Function: void mpz_gcdext (mpz_t G, mpz_t S, mpz_t T, mpz_t A, mpz_t
906: B)
907: Compute G, S, and T, such that AS + BT = G = `gcd' (A, B). If T is
908: NULL, that argument is not computed.
909:
910: - Function: int mpz_invert (mpz_t ROP, mpz_t OP1, mpz_t OP2)
911: Compute the inverse of OP1 modulo OP2 and put the result in ROP.
912: Return non-zero if an inverse exist, zero otherwise. When the
913: function returns zero, do not assume anything about the value in
914: ROP.
915:
916: - Function: int mpz_jacobi (mpz_t OP1, mpz_t OP2)
917: - Function: int mpz_legendre (mpz_t OP1, mpz_t OP2)
918: Compute the Jacobi and Legendre symbols, respectively.
919:
920:
921: File: gmp.info, Node: Comparison Functions, Next: Integer Logic and Bit Fiddling, Prev: Integer Arithmetic, Up: Integer Functions
922:
923: Comparison Functions
924: ====================
925:
926: - Function: int mpz_cmp (mpz_t OP1, mpz_t OP2)
927: Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
928: if OP1 = OP2, and a negative value if OP1 < OP2.
929:
930: - Macro: int mpz_cmp_ui (mpz_t OP1, unsigned long int OP2)
931: - Macro: int mpz_cmp_si (mpz_t OP1, signed long int OP2)
932: Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
933: if OP1 = OP2, and a negative value if OP1 < OP2.
934:
935: These functions are actually implemented as macros. They evaluate
936: their arguments multiple times.
937:
938: - Macro: int mpz_sgn (mpz_t OP)
939: Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.
940:
941: This function is actually implemented as a macro. It evaluates its
942: arguments multiple times.
943:
944:
945: File: gmp.info, Node: Integer Logic and Bit Fiddling, Next: I/O of Integers, Prev: Comparison Functions, Up: Integer Functions
946:
947: Logical and Bit Manipulation Functions
948: ======================================
949:
950: These functions behave as if two's complement arithmetic were used
951: (although sign-magnitude is used by the actual implementation).
952:
953: - Function: void mpz_and (mpz_t ROP, mpz_t OP1, mpz_t OP2)
954: Set ROP to OP1 logical-and OP2.
955:
956: - Function: void mpz_ior (mpz_t ROP, mpz_t OP1, mpz_t OP2)
957: Set ROP to OP1 inclusive-or OP2.
958:
959: - Function: void mpz_com (mpz_t ROP, mpz_t OP)
960: Set ROP to the one's complement of OP.
961:
962: - Function: unsigned long int mpz_popcount (mpz_t OP)
963: For non-negative numbers, return the population count of OP. For
964: negative numbers, return the largest possible value (MAX_ULONG).
965:
966: - Function: unsigned long int mpz_hamdist (mpz_t OP1, mpz_t OP2)
967: If OP1 and OP2 are both non-negative, return the hamming distance
968: between the two operands. Otherwise, return the largest possible
969: value (MAX_ULONG).
970:
971: It is possible to extend this function to return a useful value
972: when the operands are both negative, but the current
973: implementation returns MAX_ULONG in this case. *Do not depend on
974: this behavior, since it will change in future versions of the
975: library.*
976:
977: - Function: unsigned long int mpz_scan0 (mpz_t OP, unsigned long int
978: STARTING_BIT)
979: Scan OP, starting with bit STARTING_BIT, towards more significant
980: bits, until the first clear bit is found. Return the index of the
981: found bit.
982:
983: - Function: unsigned long int mpz_scan1 (mpz_t OP, unsigned long int
984: STARTING_BIT)
985: Scan OP, starting with bit STARTING_BIT, towards more significant
986: bits, until the first set bit is found. Return the index of the
987: found bit.
988:
989: - Function: void mpz_setbit (mpz_t ROP, unsigned long int BIT_INDEX)
990: Set bit BIT_INDEX in OP1.
991:
992: - Function: void mpz_clrbit (mpz_t ROP, unsigned long int BIT_INDEX)
993: Clear bit BIT_INDEX in OP1.
994:
995:
996: File: gmp.info, Node: I/O of Integers, Next: Miscellaneous Integer Functions, Prev: Integer Logic and Bit Fiddling, Up: Integer Functions
997:
998: Input and Output Functions
999: ==========================
1000:
1001: Functions that perform input from a stdio stream, and functions that
1002: output to a stdio stream. Passing a NULL pointer for a STREAM argument
1003: to any of these functions will make them read from `stdin' and write to
1004: `stdout', respectively.
1005:
1006: When using any of these functions, it is a good idea to include
1007: `stdio.h' before `gmp.h', since that will allow `gmp.h' to define
1008: prototypes for these functions.
1009:
1010: - Function: size_t mpz_out_str (FILE *STREAM, int BASE, mpz_t OP)
1011: Output OP on stdio stream STREAM, as a string of digits in base
1012: BASE. The base may vary from 2 to 36.
1013:
1014: Return the number of bytes written, or if an error occurred,
1015: return 0.
1016:
1017: - Function: size_t mpz_inp_str (mpz_t ROP, FILE *STREAM, int BASE)
1018: Input a possibly white-space preceded string in base BASE from
1019: stdio stream STREAM, and put the read integer in ROP. The base
1020: may vary from 2 to 36. If BASE is 0, the actual base is
1021: determined from the leading characters: if the first two
1022: characters are `0x' or `0X', hexadecimal is assumed, otherwise if
1023: the first character is `0', octal is assumed, otherwise decimal is
1024: assumed.
1025:
1026: Return the number of bytes read, or if an error occurred, return 0.
1027:
1028: - Function: size_t mpz_out_raw (FILE *STREAM, mpz_t OP)
1029: Output OP on stdio stream STREAM, in raw binary format. The
1030: integer is written in a portable format, with 4 bytes of size
1031: information, and that many bytes of limbs. Both the size and the
1032: limbs are written in decreasing significance order (i.e., in
1033: big-endian).
1034:
1035: The output can be read with `mpz_inp_raw'.
1036:
1037: Return the number of bytes written, or if an error occurred,
1038: return 0.
1039:
1040: The output of this can not be read by `mpz_inp_raw' from GMP 1,
1041: because of changes necessary for compatibility between 32-bit and
1042: 64-bit machines.
1043:
1044: - Function: size_t mpz_inp_raw (mpz_t ROP, FILE *STREAM)
1045: Input from stdio stream STREAM in the format written by
1046: `mpz_out_raw', and put the result in ROP. Return the number of
1047: bytes read, or if an error occurred, return 0.
1048:
1049: This routine can read the output from `mpz_out_raw' also from GMP
1050: 1, in spite of changes necessary for compatibility between 32-bit
1051: and 64-bit machines.
1052:
1053:
1054: File: gmp.info, Node: Miscellaneous Integer Functions, Prev: I/O of Integers, Up: Integer Functions
1055:
1056: Miscellaneous Functions
1057: =======================
1058:
1059: - Function: void mpz_random (mpz_t ROP, mp_size_t MAX_SIZE)
1060: Generate a random integer of at most MAX_SIZE limbs. The generated
1061: random number doesn't satisfy any particular requirements of
1062: randomness. Negative random numbers are generated when MAX_SIZE
1063: is negative.
1064:
1065: - Function: void mpz_random2 (mpz_t ROP, mp_size_t MAX_SIZE)
1066: Generate a random integer of at most MAX_SIZE limbs, with long
1067: strings of zeros and ones in the binary representation. Useful
1068: for testing functions and algorithms, since this kind of random
1069: numbers have proven to be more likely to trigger corner-case bugs.
1070: Negative random numbers are generated when MAX_SIZE is negative.
1071:
1072: - Function: size_t mpz_size (mpz_t OP)
1073: Return the size of OP measured in number of limbs. If OP is zero,
1074: the returned value will be zero.
1075:
1076: *This function is obsolete. It will disappear from future MP
1077: releases.*
1078:
1079: - Function: size_t mpz_sizeinbase (mpz_t OP, int BASE)
1080: Return the size of OP measured in number of digits in base BASE.
1081: The base may vary from 2 to 36. The returned value will be exact
1082: or 1 too big. If BASE is a power of 2, the returned value will
1083: always be exact.
1084:
1085: This function is useful in order to allocate the right amount of
1086: space before converting OP to a string. The right amount of
1087: allocation is normally two more than the value returned by
1088: `mpz_sizeinbase' (one extra for a minus sign and one for the
1089: terminating '\0').
1090:
1091:
1092: File: gmp.info, Node: Rational Number Functions, Next: Floating-point Functions, Prev: Integer Functions, Up: Top
1093:
1094: Rational Number Functions
1095: *************************
1096:
1097: This chapter describes the MP functions for performing arithmetic on
1098: rational numbers. These functions start with the prefix `mpq_'.
1099:
1100: Rational numbers are stored in objects of type `mpq_t'.
1101:
1102: All rational arithmetic functions assume operands have a canonical
1103: form, and canonicalize their result. The canonical from means that the
1104: denominator and the numerator have no common factors, and that the
1105: denominator is positive. Zero has the unique representation 0/1.
1106:
1107: Pure assignment functions do not canonicalize the assigned variable.
1108: It is the responsibility of the user to canonicalize the assigned
1109: variable before any arithmetic operations are performed on that
1110: variable. *Note that this is an incompatible change from version 1 of
1111: the library.*
1112:
1113: - Function: void mpq_canonicalize (mpq_t OP)
1114: Remove any factors that are common to the numerator and
1115: denominator of OP, and make the denominator positive.
1116:
1117: * Menu:
1118:
1119: * Initializing Rationals::
1120: * Assigning Rationals::
1121: * Simultaneous Integer Init & Assign::
1122: * Comparing Rationals::
1123: * Applying Integer Functions::
1124: * Miscellaneous Rational Functions::
1125:
1126:
1127: File: gmp.info, Node: Initializing Rationals, Next: Assigning Rationals, Prev: Rational Number Functions, Up: Rational Number Functions
1128:
1129: Initialization and Assignment Functions
1130: =======================================
1131:
1132: - Function: void mpq_init (mpq_t DEST_RATIONAL)
1133: Initialize DEST_RATIONAL and set it to 0/1. Each variable should
1134: normally only be initialized once, or at least cleared out (using
1135: the function `mpq_clear') between each initialization.
1136:
1137: - Function: void mpq_clear (mpq_t RATIONAL_NUMBER)
1138: Free the space occupied by RATIONAL_NUMBER. Make sure to call this
1139: function for all `mpq_t' variables when you are done with them.
1140:
1141: - Function: void mpq_set (mpq_t ROP, mpq_t OP)
1142: - Function: void mpq_set_z (mpq_t ROP, mpz_t OP)
1143: Assign ROP from OP.
1144:
1145: - Function: void mpq_set_ui (mpq_t ROP, unsigned long int OP1,
1146: unsigned long int OP2)
1147: - Function: void mpq_set_si (mpq_t ROP, signed long int OP1, unsigned
1148: long int OP2)
1149: Set the value of ROP to OP1/OP2. Note that if OP1 and OP2 have
1150: common factors, ROP has to be passed to `mpq_canonicalize' before
1151: any operations are performed on ROP.
1152:
1153:
1154: File: gmp.info, Node: Assigning Rationals, Next: Comparing Rationals, Prev: Initializing Rationals, Up: Rational Number Functions
1155:
1156: Arithmetic Functions
1157: ====================
1158:
1159: - Function: void mpq_add (mpq_t SUM, mpq_t ADDEND1, mpq_t ADDEND2)
1160: Set SUM to ADDEND1 + ADDEND2.
1161:
1162: - Function: void mpq_sub (mpq_t DIFFERENCE, mpq_t MINUEND, mpq_t
1163: SUBTRAHEND)
1164: Set DIFFERENCE to MINUEND - SUBTRAHEND.
1165:
1166: - Function: void mpq_mul (mpq_t PRODUCT, mpq_t MULTIPLIER, mpq_t
1167: MULTIPLICAND)
1168: Set PRODUCT to MULTIPLIER times MULTIPLICAND.
1169:
1170: - Function: void mpq_div (mpq_t QUOTIENT, mpq_t DIVIDEND, mpq_t
1171: DIVISOR)
1172: Set QUOTIENT to DIVIDEND/DIVISOR.
1173:
1174: - Function: void mpq_neg (mpq_t NEGATED_OPERAND, mpq_t OPERAND)
1175: Set NEGATED_OPERAND to -OPERAND.
1176:
1177: - Function: void mpq_inv (mpq_t INVERTED_NUMBER, mpq_t NUMBER)
1178: Set INVERTED_NUMBER to 1/NUMBER. If the new denominator is zero,
1179: this routine will divide by zero.
1180:
1181:
1182: File: gmp.info, Node: Comparing Rationals, Next: Applying Integer Functions, Prev: Assigning Rationals, Up: Rational Number Functions
1183:
1184: Comparison Functions
1185: ====================
1186:
1187: - Function: int mpq_cmp (mpq_t OP1, mpq_t OP2)
1188: Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
1189: if OP1 = OP2, and a negative value if OP1 < OP2.
1190:
1191: To determine if two rationals are equal, `mpq_equal' is faster than
1192: `mpq_cmp'.
1193:
1194: - Macro: int mpq_cmp_ui (mpq_t OP1, unsigned long int NUM2, unsigned
1195: long int DEN2)
1196: Compare OP1 and NUM2/DEN2. Return a positive value if OP1 >
1197: NUM2/DEN2, zero if OP1 = NUM2/DEN2, and a negative value if OP1 <
1198: NUM2/DEN2.
1199:
1200: This routine allows that NUM2 and DEN2 have common factors.
1201:
1202: This function is actually implemented as a macro. It evaluates its
1203: arguments multiple times.
1204:
1205: - Macro: int mpq_sgn (mpq_t OP)
1206: Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.
1207:
1208: This function is actually implemented as a macro. It evaluates its
1209: arguments multiple times.
1210:
1211: - Function: int mpq_equal (mpq_t OP1, mpq_t OP2)
1212: Return non-zero if OP1 and OP2 are equal, zero if they are
1213: non-equal. Although `mpq_cmp' can be used for the same purpose,
1214: this function is much faster.
1215:
1216:
1217: File: gmp.info, Node: Applying Integer Functions, Next: Miscellaneous Rational Functions, Prev: Comparing Rationals, Up: Rational Number Functions
1218:
1219: Applying Integer Functions to Rationals
1220: =======================================
1221:
1222: The set of `mpq' functions is quite small. In particular, there are
1223: no functions for either input or output. But there are two macros that
1224: allow us to apply any `mpz' function on the numerator or denominator of
1225: a rational number. If these macros are used to assign to the rational
1226: number, `mpq_canonicalize' normally need to be called afterwards.
1227:
1228: - Macro: mpz_t mpq_numref (mpq_t OP)
1229: - Macro: mpz_t mpq_denref (mpq_t OP)
1230: Return a reference to the numerator and denominator of OP,
1231: respectively. The `mpz' functions can be used on the result of
1232: these macros.
1233:
1234:
1235: File: gmp.info, Node: Miscellaneous Rational Functions, Prev: Applying Integer Functions, Up: Rational Number Functions
1236:
1237: Miscellaneous Functions
1238: =======================
1239:
1240: - Function: double mpq_get_d (mpq_t OP)
1241: Convert OP to a double.
1242:
1243: These functions assign between either the numerator or denominator
1244: of a rational, and an integer. Instead of using these functions, it is
1245: preferable to use the more general mechanisms `mpq_numref' and
1246: `mpq_denref', together with `mpz_set'.
1247:
1248: - Function: void mpq_set_num (mpq_t RATIONAL, mpz_t NUMERATOR)
1249: Copy NUMERATOR to the numerator of RATIONAL. When this risks to
1250: make the numerator and denominator of RATIONAL have common
1251: factors, you have to pass RATIONAL to `mpq_canonicalize' before
1252: any operations are performed on RATIONAL.
1253:
1254: This function is equivalent to `mpz_set (mpq_numref (RATIONAL),
1255: NUMERATOR)'.
1256:
1257: - Function: void mpq_set_den (mpq_t RATIONAL, mpz_t DENOMINATOR)
1258: Copy DENOMINATOR to the denominator of RATIONAL. When this risks
1259: to make the numerator and denominator of RATIONAL have common
1260: factors, or if the denominator might be negative, you have to pass
1261: RATIONAL to `mpq_canonicalize' before any operations are performed
1262: on RATIONAL.
1263:
1264: *In version 1 of the library, negative denominators were handled by
1265: copying the sign to the numerator. That is no longer done.*
1266:
1267: This function is equivalent to `mpz_set (mpq_denref (RATIONAL),
1268: DENOMINATORS)'.
1269:
1270: - Function: void mpq_get_num (mpz_t NUMERATOR, mpq_t RATIONAL)
1271: Copy the numerator of RATIONAL to the integer NUMERATOR, to
1272: prepare for integer operations on the numerator.
1273:
1274: This function is equivalent to `mpz_set (NUMERATOR, mpq_numref
1275: (RATIONAL))'.
1276:
1277: - Function: void mpq_get_den (mpz_t DENOMINATOR, mpq_t RATIONAL)
1278: Copy the denominator of RATIONAL to the integer DENOMINATOR, to
1279: prepare for integer operations on the denominator.
1280:
1281: This function is equivalent to `mpz_set (DENOMINATOR, mpq_denref
1282: (RATIONAL))'.
1283:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to gmp.info-1 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gmp