Annotation of OpenXM/src/kan96xx/gmp-2.0.2/gmp.info, Revision 1.1.1.1
1.1 maekawa 1: Info file: gmp.info, -*-Text-*-
2: produced by `texinfo-format-buffer'
3: from file `gmp.texi'
4: using `texinfmt.el' version 2.32 of 19 November 1993.
5:
6:
7: START-INFO-DIR-ENTRY
8: * gmp: (gmp.info). GNU Multiple Precision Arithmetic Library.
9: END-INFO-DIR-ENTRY
10:
11:
12:
13:
14:
15:
16: This file documents GNU MP, a library for arbitrary-precision
17: arithmetic.
18:
19: Copyright (C) 1991, 1993, 1994, 1995, 1996 Free Software Foundation,
20: Inc.
21:
22: Permission is granted to make and distribute verbatim copies of this
23: manual provided the copyright notice and this permission notice are
24: preserved on all copies.
25:
26: Permission is granted to copy and distribute modified versions of this
27: manual under the conditions for verbatim copying, provided that the
28: entire resulting derived work is distributed under the terms of a
29: permission notice identical to this one.
30:
31: Permission is granted to copy and distribute translations of this manual
32: into another language, under the above conditions for modified versions,
33: except that this permission notice may be stated in a translation
34: approved by the Foundation.
35:
36:
37:
38: File: gmp.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
39:
40:
41: GNU MP
42: ******
43:
44: This manual documents how to install and use the GNU multiple precision
45: arithmetic library, version 2.0.2.
46:
47:
48: * Menu:
49:
50: * Copying:: GMP Copying Conditions (LGPL).
51: * Introduction to MP:: Brief introduction to GNU MP.
52: * Installing MP:: How to configure and compile the MP library.
53: * MP Basics:: What every MP user should now.
54: * Reporting Bugs:: How to usefully report bugs.
55: * Integer Functions:: Functions for arithmetic on signed integers.
56: * Rational Number Functions:: Functions for arithmetic on rational numbers.
57: * Floating-point Functions:: Functions for arithmetic on floats.
58: * Low-level Functions:: Fast functions for natural numbers.
59: * BSD Compatible Functions:: All functions found in BSD MP.
60: * Custom Allocation:: How to customize the internal allocation.
61:
62: * Contributors::
63: * References::
64: * Concept Index::
65: * Function Index::
66:
67:
68: File: gmp.info, Node: Copying, Next: Introduction to MP, Prev: Top, Up: Top
69:
70: GNU MP Copying Conditions
71: *************************
72:
73: This library is "free"; this means that everyone is free to use it and
74: free to redistribute it on a free basis. The library is not in the
75: public domain; it is copyrighted and there are restrictions on its
76: distribution, but these restrictions are designed to permit everything
77: that a good cooperating citizen would want to do. What is not allowed
78: is to try to prevent others from further sharing any version of this
79: library that they might get from you.
80:
81: Specifically, we want to make sure that you have the right to give away
82: copies of the library, that you receive source code or else can get it
83: if you want it, that you can change this library or use pieces of it in
84: new free programs, and that you know you can do these things.
85:
86: To make sure that everyone has such rights, we have to forbid you to
87: deprive anyone else of these rights. For example, if you distribute
88: copies of the GNU MP library, you must give the recipients all the
89: rights that you have. You must make sure that they, too, receive or can
90: get the source code. And you must tell them their rights.
91:
92: Also, for our own protection, we must make certain that everyone finds
93: out that there is no warranty for the GNU MP library. If it is modified
94: by someone else and passed on, we want their recipients to know that
95: what they have is not what we distributed, so that any problems
96: introduced by others will not reflect on our reputation.
97:
98: The precise conditions of the license for the GNU MP library are found
99: in the Library General Public License that accompany the source code.
100:
101:
102: File: gmp.info, Node: Introduction to MP, Next: Installing MP, Prev: Copying, Up: Top
103:
104: Introduction to GNU MP
105: **********************
106:
107:
108: GNU MP is a portable library written in C for arbitrary precision
109: arithmetic on integers, rational numbers, and floating-point numbers.
110: It aims to provide the fastest possible arithmetic for all applications
111: that need higher precision than is directly supported by the basic C
112: types.
113:
114: Many applications use just a few hundred bits of precision; but some
115: applications may need thousands or even millions of bits. MP is
116: designed to give good performance for both, by choosing algorithms based
117: on the sizes of the operands, and by carefully keeping the overhead at a
118: minimum.
119:
120: The speed of MP is achieved by using fullwords as the basic arithmetic
121: type, by using sophisticated algorithms, by including carefully
122: optimized assembly code for the most common inner loops for many
123: different CPUs, and by a general emphasis on speed (as opposed to
124: simplicity or elegance).
125:
126: There is carefully optimized assembly code for these CPUs: DEC Alpha,
127: Amd 29000, HPPA 1.0 and 1.1, Intel Pentium and generic x86, Intel i960,
128: Motorola MC68000, MC68020, MC88100, and MC88110, Motorola/IBM PowerPC,
129: National NS32000, IBM POWER, MIPS R3000, R4000, SPARCv7, SuperSPARC,
130: generic SPARCv8, and DEC VAX. Some optimizations also for ARM, Clipper,
131: IBM ROMP (RT), and Pyramid AP/XP.
132:
133: This version of MP is released under a more liberal license than
134: previous versions. It is now permitted to link MP to non-free programs,
135: as long as MP source code is provided when distributing the non-free
136: program.
137:
138:
139:
140: How to use this Manual
141: ======================
142:
143: Everyone should read *Note MP Basics::. If you need to install the
144: library yourself, you need to read *Note Installing MP::, too.
145:
146: The rest of the manual can be used for later reference, although it is
147: probably a good idea to glance through it.
148:
149:
150:
151: File: gmp.info, Node: Installing MP, Next: MP Basics, Prev: Introduction to MP, Up: Top
152:
153: Installing MP
154: *************
155:
156: To build MP, you first have to configure it for your CPU and operating
157: system. You need a C compiler, preferably GCC, but any reasonable
158: compiler should work. And you need a standard Unix `make' program, plus
159: some other standard Unix utility programs.
160:
161: (If you're on an MS-DOS machine, your can build MP using `make.bat'. It
162: requires that djgpp is installed. It does not require configuration,
163: nor is `make' needed; `make.bat' both configures and builds the
164: library.)
165:
166: Here are the steps needed to install the library on Unix systems:
167:
168: 1. In most cases, `./configure --target=cpu-vendor-os', should work
169: both for native and cross-compilation. If you get error messages,
170: your machine might not be supported.
171:
172: If you want to compile in a separate object directory, cd to that
173: directory, and prefix the configure command with the path to the MP
174: source directory. Not all `make' programs have the necessary
175: features to support this. In particular, SunOS and Slowaris `make'
176: have bugs that makes them unable to build from a separate object
177: directory. Use GNU `make' instead.
178:
179: In addition to the standard cpu-vendor-os tuples, MP recognizes
180: sparc8 and supersparc as valid CPU names. Specifying these CPU
181: names for relevant systems will improve performance significantly.
182:
183: In general, if you want a library that runs as fast as possible,
184: you should make sure you configure MP for the exact CPU type your
185: system uses.
186:
187: If you have `gcc' in your `PATH', it will be used by default. To
188: override this, pass `-with-gcc=no' to `configure'.
189:
190: 2. `make'
191:
192: This will compile MP, and create a library archive file `libgmp.a'
193: in the working directory.
194:
195: 3. `make check'
196:
197: This will make sure MP was built correctly. If you get error
198: messages, please report this to `bug-gmp@prep.ai.mit.edu'. (*Note
199: Reporting Bugs::, for information on what to include in useful bug
200: reports.)
201:
202: 4. `make install'
203:
204: This will copy the file `gmp.h' and `libgmp.a', as well as the info
205: files, to `/usr/local' (or if you passed the `--prefix' option to
206: `configure', to the directory given as argument to `--prefix').
207:
208: If you wish to build and install the BSD MP compatible functions, use
209: `make libmp.a' and `make install-bsdmp'.
210:
211: There are some other useful make targets:
212:
213: * `doc'
214:
215: Create a DVI version of the manual, in `gmp.dvi' and a set of info
216: files, in `gmp.info', `gmp.info-1', `gmp.info-2', etc.
217:
218: * `ps'
219:
220: Create a Postscript version of the manual, in `gmp.ps'.
221:
222: * `html'
223:
224: Create a HTML version of the manual, in `gmp.html'.
225:
226: * `clean'
227:
228: Delete all object files and archive files, but not the
229: configuration files.
230:
231: * `distclean'
232:
233: Delete all files not included in the distribution.
234:
235: * `uninstall'
236:
237: Delete all files copied by `make install'.
238:
239:
240:
241: Known Build Problems
242: ====================
243:
244: GCC 2.7.2 (as well as 2.6.3) for the RS/6000 and PowerPC can not be used
245: to compile MP, due to a bug in GCC. If you want to use GCC for these
246: machines, you need to apply the patch below to GCC, or use a later
247: version of the compiler.
248:
249: If you are on a Sequent Symmetry, use the GNU assembler instead of the
250: system's assembler, since the latter has serious bugs.
251:
252: The system compiler on NeXT is a massacred and old gcc, even if the
253: compiler calls itself `cc'. This compiler cannot be used to build MP.
254: You need to get a real gcc, and install that before you compile MP.
255: (NeXT might have fixed this in newer releases of their system.)
256:
257: The system C compiler under SunOS 4 has a bug that makes it miscompile
258: mpq/get_d.c. This will make `make check' fail.
259:
260: Please report other problems to `bug-gmp@prep.ai.mit.edu'.
261: *Note Reporting Bugs::.
262:
263:
264: Patch to apply to GCC 2.6.3 and 2.7.2:
265:
266: *** config/rs6000/rs6000.md Sun Feb 11 08:22:11 1996
267: --- config/rs6000/rs6000.md.new Sun Feb 18 03:33:37 1996
268: ***************
269: *** 920,926 ****
270: (set (match_operand:SI 0 "gpc_reg_operand" "=r")
271: (not:SI (match_dup 1)))]
272: ""
273: ! "nor. %0,%2,%1"
274: [(set_attr "type" "compare")])
275:
276: (define_insn ""
277: --- 920,926 ----
278: (set (match_operand:SI 0 "gpc_reg_operand" "=r")
279: (not:SI (match_dup 1)))]
280: ""
281: ! "nor. %0,%1,%1"
282: [(set_attr "type" "compare")])
283:
284: (define_insn ""
285:
286:
287: File: gmp.info, Node: MP Basics, Next: Reporting Bugs, Prev: Installing MP, Up: Top
288:
289: MP Basics
290: *********
291:
292:
293: All declarations needed to use MP are collected in the include file
294: `gmp.h'. It is designed to work with both C and C++ compilers.
295:
296:
297:
298: Nomenclature and Types
299: ======================
300:
301: In this manual, "integer" usually means a multiple precision integer, as
302: defined by the MP library. The C data type for such integers is
303: `mpz_t'. Here are some examples of how to declare such integers:
304:
305: mpz_t sum;
306:
307: struct foo { mpz_t x, y; };
308:
309: mpz_t vec[20];
310:
311: "Rational number" means a multiple precision fraction. The C data type
312: for these fractions is `mpq_t'. For example:
313:
314: mpq_t quotient;
315:
316: "Floating point number" or "Float" for short, is an arbitrary precision
317: mantissa with an limited precision exponent. The C data type for such
318: objects is `mpf_t'.
319:
320: A "limb" means the part of a multi-precision number that fits in a
321: single word. (We chose this word because a limb of the human body is
322: analogous to a digit, only larger, and containing several digits.)
323: Normally a limb contains 32 or 64 bits. The C data type for a limb is
324: `mp_limb_t'.
325:
326:
327:
328: Function Classes
329: ================
330:
331: There are six classes of functions in the MP library:
332:
333: 1. Functions for signed integer arithmetic, with names beginning with
334: `mpz_'. The associated type is `mpz_t'. There are about 100
335: functions in this class.
336:
337: 2. Functions for rational number arithmetic, with names beginning with
338: `mpq_'. The associated type is `mpq_t'. There are about 20
339: functions in this class, but the functions in the previous class
340: can be used for performing arithmetic on the numerator and
341: denominator separately.
342:
343: 3. Functions for floating-point arithmetic, with names beginning with
344: `mpf_'. The associated type is `mpf_t'. There are about 50
345: functions is this class.
346:
347: 4. Functions compatible with Berkeley MP, such as `itom', `madd', and
348: `mult'. The associated type is `MINT'.
349:
350: 5. Fast low-level functions that operate on natural numbers. These
351: are used by the functions in the preceding groups, and you can also
352: call them directly from very time-critical user programs. These
353: functions' names begin with `mpn_'. There are about 30
354: (hard-to-use) functions in this class.
355:
356: The associated type is array of `mp_limb_t'.
357:
358: 6. Miscellaneous functions. Functions for setting up custom
359: allocation.
360:
361:
362:
363: MP Variable Conventions
364: =======================
365:
366: As a general rule, all MP functions expect output arguments before input
367: arguments. This notation is based on an analogy with the assignment
368: operator. (The BSD MP compatibility functions disobey this rule, having
369: the output argument(s) last.)
370:
371: MP allows you to use the same variable for both input and output in the
372: same expression. For example, the main function for integer
373: multiplication, `mpz_mul', can be used like this: `mpz_mul (x, x, x)'.
374: This computes the square of X and puts the result back in X.
375:
376: Before you can assign to an MP variable, you need to initialize it by
377: calling one of the special initialization functions. When you're done
378: with a variable, you need to clear it out, using one of the functions
379: for that purpose. Which function to use depends on the type of
380: variable. See the chapters on integer functions, rational number
381: functions, and floating-point functions for details.
382:
383: A variable should only be initialized once, or at least cleared out
384: between each initialization. After a variable has been initialized, it
385: may be assigned to any number of times.
386:
387: For efficiency reasons, avoid to initialize and clear out a variable in
388: loops. Instead, initialize it before entering the loop, and clear it
389: out after the loop has exited.
390:
391: You don't need to be concerned about allocating additional space for MP
392: variables. All functions in MP automatically allocate additional space
393: when a variable does not already have enough space. They do not,
394: however, reduce the space when a smaller number is stored in the object.
395: Most of the time, this policy is best, since it avoids frequent
396: re-allocation.
397:
398:
399:
400: Useful Macros and Constants
401: ===========================
402:
403: -- Global Constant: const int mp_bits_per_limb
404: The number of bits per limb.
405:
406: -- Macro: __GNU_MP_VERSION
407: -- Macro: __GNU_MP_VERSION_MINOR
408: The major and minor MP version, respectively, as integers.
409:
410:
411: Compatibility with Version 1.x
412: ==============================
413:
414: This version of MP is upward compatible with previous versions of MP,
415: with a few exceptions.
416:
417: @item Integer division functions round the result differently. The old
418: functions (@code{mpz_div}, @code{mpz_divmod}, @code{mpz_mdiv},
419: @code{mpz_mdivmod}, etc) now all use floor rounding (i.e., they round the
420: quotient to @minus{}infinity). There are a lot of new functions for integer
421: division, giving the user better control over the rounding.@refill
422:
423: @item The function @code{mpz_mod} now compute the true @strong{mod} function.
424:
425: @item The functions @code{mpz_powm} and @code{mpz_powm_ui} now use
426: @strong{mod} for reduction.
427:
428: @item The assignment functions for rational numbers do no longer canonicalize
429: their results. In the case a non-canonical result could arise from an
430: assignment, the user need to insert an explicit call to
431: @code{mpq_canonicalize}. This change was made for efficiency.@refill
432:
433: @item Output generated by @code{mpz_out_raw} in this release cannot be read
434: by @code{mpz_inp_raw} in previous releases. This change was made for making
435: the file format truly portable between machines with different word sizes.@refill
436:
437: @item Several @code{mpn} functions have changed. But they were intentionally
438: undocumented in previous releases.@refill
439:
440: @item The functions @code{mpz_cmp_ui}, @code{mpz_cmp_si}, and @code{mpq_cmp_ui}
441: are now implementated as macros, and thereby sometimes evaluate their
442: arguments multiple times.@refill
443:
444: @item The functions @code{mpz_pow_ui} and @code{mpz_ui_pow_ui} now yield 1
445: for 0^0. (In version 1, they yielded 0.)@refill
446:
447: @end enumerate
448:
449:
450: @section Getting the Latest Version of MP
451:
452: The latest version of the MP library is available by anonymous ftp from
453: from @samp{prep.ai.mit.edu}. The file name is
454: @file{/pub/gnu/gmp-M.N.tar.gz}. Many sites around the world mirror
455: @samp{prep}; please use a mirror site near you.@refill
456:
457: @node Reporting Bugs, Integer Functions, MP Basics, Top
458: @comment node-name, next, previous, up
459: @chapter Reporting Bugs
460: @cindex Reporting bugs
461:
462: If you think you have found a bug in the MP library, please investigate it and
463: report it. We have made this library available to you, and it is not to ask
464: too much from you, to ask you to report the bugs that you find.@refill
465:
466: There are a few things you should think about when you put your bug report
467: together.@refill
468:
469: You have to send us a test case that makes it possible for us to reproduce the
470: bug. Include instructions on how to run the test case.@refill
471:
472: You also have to explain what is wrong; if you get a crash, or if the results
473: printed are incorrect and in that case, in what way.@refill
474:
475: It is not uncommon that an observed problem is actually due to a bug in the
476: compiler used when building MP; the MP code tends to explore interesting
477: corners in compilers. Therefore, please include compiler version information
478: in your bug report. This can be extracted using @samp{what `which cc`}, or,
479: if you're using gcc, @samp{gcc -v}. Also, include the output from @samp{uname
480: -a}.@refill
481:
482: If your bug report is good, we will do our best to help you to get a corrected
483: version of the library; if the bug report is poor, we won't do anything about
484: it (aside of chiding you to send better bug reports).@refill
485:
486: Send your bug report to: @samp{bug-gmp@@prep.ai.mit.edu}.@refill
487:
488: If you think something in this manual is unclear, or downright incorrect, or if
489: the language needs to be improved, please send a note to the same address.@refill
490:
491:
492: @node Integer Functions, Rational Number Functions, Reporting Bugs, Top
493: @comment node-name, next, previous, up
494: @chapter Integer Functions
495: @cindex Integer functions
496:
497: This chapter describes the MP functions for performing integer arithmetic.
498: These functions start with the prefix @code{mpz_}.@refill
499:
500: Arbitrary precision integers are stored in objects of type @code{mpz_t}.@refill
501:
502: @menu
503: * Initializing Integers::
504: * Assigning Integers::
505: * Simultaneous Integer Init & Assign::
506: * Converting Integers::
507: * Integer Arithmetic::
508: * Comparison Functions::
509: * Integer Logic and Bit Fiddling::
510: * I/O of Integers::
511: * Miscellaneous Integer Functions::
512: @end menu
513:
514: @node Initializing Integers, Assigning Integers, , Integer Functions
515: @comment node-name, next, previous, up
516: @section Initialization and Assignment Functions
517:
518: The functions for integer arithmetic assume that all integer objects are
519: initialized. You do that by calling the function @code{mpz_init}.@refill
520:
521: @deftypefun void mpz_init (mpz_t @var{integer})
522: Initialize @var{integer} with limb space and set the initial numeric value to
523: 0. Each variable should normally only be initialized once, or at least cleared
524: out (using @code{mpz_clear}) between each initialization.@refill
525: @end deftypefun
526:
527: Here is an example of using @code{mpz_init}:@refill
528:
529: @example
530: @{
531: mpz_t integ;
532: mpz_init (integ);
533: @dots{}
534: mpz_add (integ, @dots{});
535: @dots{}
536: mpz_sub (integ, @dots{});
537:
538: /* Unless the program is about to exit, do ... */
539: mpz_clear (integ);
540: @}
541: @end example
542:
543: @noindent
544: As you can see, you can store new values any number of times, once an
545: object is initialized.@refill
546:
547: @deftypefun void mpz_clear (mpz_t @var{integer})
548: Free the limb space occupied by @var{integer}. Make sure to call this
549: function for all @code{mpz_t} variables when you are done with them.@refill
550: @end deftypefun
551:
552: @deftypefun {void *} _mpz_realloc (mpz_t @var{integer}, mp_size_t @var{new_alloc})
553: Change the limb space allocation to @var{new_alloc} limbs. This function is
554: not normally called from user code, but it can be used to give memory back to
555: the heap, or to increase the space of a variable to avoid repeated automatic
556: re-allocation.@refill
557: @end deftypefun
558:
559: @deftypefun void mpz_array_init (mpz_t @var{integer_array}[], size_t @var{array_size}, mp_size_t @var{fixed_num_bits})
560: Allocate @strong{fixed} limb space for all @var{array_size} integers in
561: @var{integer_array}. The fixed allocation for each integer in the array is
562: enough to store @var{fixed_num_bits}. If the fixed space will be insufficient
563: for storing the result of a subsequent calculation, the result is
564: unpredictable.@refill
565:
566: This function is useful for decreasing the working set for some algorithms
567: that use large integer arrays.@refill
568:
569: There is no way to de-allocate the storage allocated by this function.
570: Don't call @code{mpz_clear}!@refill
571: @end deftypefun
572:
573:
574: @node Assigning Integers, Simultaneous Integer Init & Assign, Initializing Integers, Integer Functions
575: @comment node-name, next, previous, up
576: @subsection Assignment Functions
577: @cindex Integer assignment functions
578:
579: These functions assign new values to already initialized integers
580: (@pxref{Initializing Integers}).@refill
581:
582: @deftypefun void mpz_set (mpz_t @var{rop}, mpz_t @var{op})
583: @deftypefunx void mpz_set_ui (mpz_t @var{rop}, unsigned long int @var{op})
584: @deftypefunx void mpz_set_si (mpz_t @var{rop}, signed long int @var{op})
585: @deftypefunx void mpz_set_d (mpz_t @var{rop}, double @var{op})
586: @deftypefunx void mpz_set_q (mpz_t @var{rop}, mpq_t @var{op})
587: @deftypefunx void mpz_set_f (mpz_t @var{rop}, mpf_t @var{op})
588: Set the value of @var{rop} from @var{op}.@refill
589: @end deftypefun
590:
591: @deftypefun int mpz_set_str (mpz_t @var{rop}, char *@var{str}, int @var{base})
592: Set the value of @var{rop} from @var{str}, a '\0'-terminated C string in base
593: @var{base}. White space is allowed in the string, and is simply ignored. The
594: base may vary from 2 to 36. If @var{base} is 0, the actual base is determined
595: from the leading characters: if the first two characters are `0x' or `0X',
596: hexadecimal is assumed, otherwise if the first character is `0', octal is
597: assumed, otherwise decimal is assumed.@refill
598:
599: This function returns 0 if the entire string up to the '\0' is a valid
600: number in base @var{base}. Otherwise it returns @minus{}1.@refill
601: @end deftypefun
602:
603:
604: @node Simultaneous Integer Init & Assign, Converting Integers, Assigning Integers, Integer Functions
605: @comment node-name, next, previous, up
606: @subsection Combined Initialization and Assignment Functions
607: @cindex Initialization and assignment functions
608:
609: For convenience, MP provides a parallel series of initialize-and-set functions
610: which initialize the output and then store the value there. These functions'
611: names have the form @code{mpz_init_set@dots{}}@refill
612:
613: Here is an example of using one:@refill
614:
615: @example
616: @{
617: mpz_t pie;
618: mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10);
619: @dots{}
620: mpz_sub (pie, @dots{});
621: @dots{}
622: mpz_clear (pie);
623: @}
624: @end example
625:
626: @noindent
627: Once the integer has been initialized by any of the @code{mpz_init_set@dots{}}
628: functions, it can be used as the source or destination operand for the ordinary
629: integer functions. Don't use an initialize-and-set function on a variable
630: already initialized!@refill
631:
632: @deftypefun void mpz_init_set (mpz_t @var{rop}, mpz_t @var{op})
633: @deftypefunx void mpz_init_set_ui (mpz_t @var{rop}, unsigned long int @var{op})
634: @deftypefunx void mpz_init_set_si (mpz_t @var{rop}, signed long int @var{op})
635: @deftypefunx void mpz_init_set_d (mpz_t @var{rop}, double @var{op})
636: Initialize @var{rop} with limb space and set the initial numeric value from
637: @var{op}.@refill
638: @end deftypefun
639:
640: @deftypefun int mpz_init_set_str (mpz_t @var{rop}, char *@var{str}, int @var{base})
641: Initialize @var{rop} and set its value like @code{mpz_set_str} (see its
642: documentation above for details).@refill
643:
644: If the string is a correct base @var{base} number, the function returns 0;
645: if an error occurs it returns @minus{}1. @var{rop} is initialized even if
646: an error occurs. (I.e., you have to call @code{mpz_clear} for it.)@refill
647: @end deftypefun
648:
649:
650: @node Converting Integers, Integer Arithmetic, Simultaneous Integer Init & Assign, Integer Functions
651: @comment node-name, next, previous, up
652: @section Conversion Functions
653: @cindex Integer conversion functions
654: @cindex Conversion functions
655:
656: This section describes functions for converting arbitrary precision integers
657: to standard C types. Functions for converting @emph{to} arbitrary
658: precision integers are described in @ref{Assigning Integers} and @ref{I/O of
659: Integers}.@refill
660:
661: @deftypefun {unsigned long int} mpz_get_ui (mpz_t @var{op})
662: Return the least significant part from @var{op}. This function combined
663: with @* @code{mpz_tdiv_q_2exp(@dots{}, @var{op}, CHAR_BIT*sizeof(unsigned
664: long int))} can be used to extract the limbs of an integer.
665: @end deftypefun
666:
667: @deftypefun {signed long int} mpz_get_si (mpz_t @var{op})
668: If @var{op} fits into a @code{signed long int} return the value of @var{op}.
669: Otherwise return the least significant part of @var{op}, with the same sign
670: as @var{op}.@refill
671:
672: If @var{op} is too large to fit in a @code{signed long int}, the returned
673: result is probably not very useful. @c To find out if the value will fit, use@refill
674: @c the function @code{mpz_fits_si}.
675: @end deftypefun
676:
677: @deftypefun double mpz_get_d (mpz_t @var{op})
678: Convert @var{op} to a double.@refill
679: @end deftypefun
680:
681: @deftypefun {char *} mpz_get_str (char *@var{str}, int @var{base}, mpz_t @var{op})
682: Convert @var{op} to a string of digits in base @var{base}. The base may vary
683: from 2 to 36.@refill
684:
685: If @var{str} is NULL, space for the result string is allocated using the
686: default allocation function, and a pointer to the string is returned.@refill
687:
688: If @var{str} is not NULL, it should point to a block of storage enough large
689: for the result. To find out the right amount of space to provide for
690: @var{str}, use @code{mpz_sizeinbase (@var{op}, @var{base}) + 2}. The two
691: extra bytes are for a possible minus sign, and for the terminating null
692: character.@refill
693: @end deftypefun
694:
695:
696: @node Integer Arithmetic, Comparison Functions, Converting Integers, Integer Functions
697: @comment node-name, next, previous, up
698: @section Arithmetic Functions
699: @cindex Integer arithmetic functions
700: @cindex Arithmetic functions
701:
702: @deftypefun void mpz_add (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
703: @deftypefunx void mpz_add_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
704: @ifinfo
705: Set @var{rop} to @var{op1} + @var{op2}.@refill
706: @end ifinfo
707: @iftex
708: @tex
709: Set @var{rop} to $@var{op1} + @var{op2}$.
710: @end tex
711: @end iftex
712: @end deftypefun
713:
714: @deftypefun void mpz_sub (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
715: @deftypefunx void mpz_sub_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
716: Set @var{rop} to @var{op1} @minus{} @var{op2}.@refill
717: @end deftypefun
718:
719: @deftypefun void mpz_mul (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
720: @deftypefunx void mpz_mul_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
721: @ifinfo
722: Set @var{rop} to @var{op1} times @var{op2}.@refill
723: @end ifinfo
724: @iftex
725: @tex
726: Set @var{rop} to $@var{op1} \times @var{op2}$.
727: @end tex
728: @end iftex
729: @end deftypefun
730:
731: @deftypefun void mpz_mul_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
732: @ifinfo
733: Set @var{rop} to @var{op1} times 2 raised to @var{op2}. This operation can
734: also be defined as a left shift, @var{op2} steps.@refill
735: @end ifinfo
736: @iftex
737: @tex
738: Set @var{rop} to $@var{op1} \times 2^{op2}$. This operation can also be
739: defined as a left shift, @var{op2} steps.
740: @end tex
741: @end iftex
742: @end deftypefun
743:
744: @deftypefun void mpz_neg (mpz_t @var{rop}, mpz_t @var{op})
745: Set @var{rop} to @minus{}@var{op}.@refill
746: @end deftypefun
747:
748: @deftypefun void mpz_abs (mpz_t @var{rop}, mpz_t @var{op})
749: Set @var{rop} to the absolute value of @var{op}.@refill
750: @end deftypefun
751:
752: @deftypefun void mpz_fac_ui (mpz_t @var{rop}, unsigned long int @var{op})
753: Set @var{rop} to @var{op}!, the factorial of @var{op}.@refill
754: @end deftypefun
755:
756: @subsection Division functions
757:
758: Division is undefined if the divisor is zero, and passing a zero divisor to
759: the divide or modulo functions, as well passing a zero mod argument to the
760: @code{mpz_powm} and @code{mpz_powm_ui} functions, will make these functions
761: intentionally divide by zero. This gives the user the possibility to handle
762: arithmetic exceptions in these functions in the same manner as other
763: arithmetic exceptions.@refill
764:
765: There are three main groups of division functions:@refill
766: @itemize @bullet
767: @item
768: Functions that truncate the quotient towards 0. The names of these
769: functions start with @code{mpz_tdiv}. The @samp{t} in the name is short for
770: @samp{truncate}.@refill
771: @item
772: Functions that round the quotient towards @minus{}infinity. The names of
773: these routines start with @code{mpz_fdiv}. The @samp{f} in the name is
774: short for @samp{floor}.@refill
775: @item
776: Functions that round the quotient towards +infinity. The names of
777: these routines start with @code{mpz_cdiv}. The @samp{c} in the name is
778: short for @samp{ceil}.@refill
779: @end itemize
780:
781: For each rounding mode, there are a couple of variants. Here @samp{q} means
782: that the quotient is computed, while @samp{r} means that the remainder is
783: computed. Functions that compute both the quotient and remainder have
784: @samp{qr} in the name.@refill
785:
786: @deftypefun void mpz_tdiv_q (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
787: @deftypefunx void mpz_tdiv_q_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
788: Set @var{rop} to [@var{op1}/@var{op2}]. The quotient is truncated towards
789: 0.@refill
790: @end deftypefun
791:
792: @deftypefun void mpz_tdiv_r (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
793: @deftypefunx void mpz_tdiv_r_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
794: Set @var{rop} to (@var{op1} - [@var{op1}/@var{op2}] * @var{op2}).
795: Unless the remainder is zero, it has the same sign as the dividend.@refill
796: @end deftypefun
797:
798: @deftypefun void mpz_tdiv_qr (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, mpz_t @var{op2})
799: @deftypefunx void mpz_tdiv_qr_ui (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, unsigned long int @var{op2})
800: Divide @var{op1} by @var{op2} and put the quotient in @var{rop1} and the
801: remainder in @var{rop2}. The quotient is rounded towards 0. Unless the
802: remainder is zero, it has the same sign as the dividend.@refill
803:
804: If @var{rop1} and @var{rop2} are the same variable, the results are
805: undefined.@refill
806: @end deftypefun
807:
808: @deftypefun void mpz_fdiv_q (mpz_t @var{rop1}, mpz_t @var{op1}, mpz_t @var{op2})
809: @deftypefunx void mpz_fdiv_q_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
810: @ifinfo
811: Set @var{rop} to @var{op1}/@var{op2}. The quotient is rounded towards
812: @minus{}infinity.@refill
813: @end ifinfo
814: @iftex
815: @tex
816: Set @var{rop} to $\lfloor@var{op1}/@var{op2}\rfloor$. (I.e., round
817: the quotient towards $-\infty$.)
818: @end tex
819: @end iftex
820: @end deftypefun
821:
822: @deftypefun void mpz_fdiv_r (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
823: @deftypefunx {unsigned long int} mpz_fdiv_r_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
824: Divide @var{op1} by @var{op2} and put the remainder in @var{rop}. Unless
825: the remainder is zero, it has the same sign as the divisor.@refill
826:
827: For @code{mpz_fdiv_r_ui} the remainder is small enough to fit in an
828: @code{unsigned long int}, and is therefore returned.@refill
829: @end deftypefun
830:
831: @deftypefun void mpz_fdiv_qr (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, mpz_t @var{op2})
832: @deftypefunx {unsigned long int} mpz_fdiv_qr_ui (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, unsigned long int @var{op2})
833: Divide @var{op1} by @var{op2} and put the quotient in @var{rop1} and the
834: remainder in @var{rop2}. The quotient is rounded towards @minus{}infinity.
835: Unless the remainder is zero, it has the same sign as the divisor.@refill
836:
837: For @code{mpz_fdiv_qr_ui} the remainder is small enough to fit in an
838: @code{unsigned long int}, and is therefore returned.@refill
839:
840: If @var{rop1} and @var{rop2} are the same variable, the results are
841: undefined.@refill
842: @end deftypefun
843:
844: @deftypefun {unsigned long int} mpz_fdiv_ui (mpz_t @var{op1}, unsigned long int @var{op2})
845: This function is similar to @code{mpz_fdiv_r_ui}, but the remainder is only
846: returned; it is not stored anywhere.@refill
847: @end deftypefun
848:
849: @deftypefun void mpz_cdiv_q (mpz_t @var{rop1}, mpz_t @var{op1}, mpz_t @var{op2})
850: @deftypefunx void mpz_cdiv_q_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
851: @ifinfo
852: Set @var{rop} to @var{op1}/@var{op2}. The quotient is rounded towards
853: +infinity.@refill
854: @end ifinfo
855: @iftex
856: @tex
857: Set @var{rop} to $\lceil@var{op1}/@var{op2}\rceil$. (I.e., round the
858: quotient towards $+\infty$.)
859: @end tex
860: @end iftex
861: @end deftypefun
862:
863: @deftypefun void mpz_cdiv_r (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
864: @deftypefunx {unsigned long int} mpz_cdiv_r_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
865: Divide @var{op1} by @var{op2} and put the remainder in @var{rop}. Unless
866: the remainder is zero, it has the opposite sign as the divisor.@refill
867:
868: For @code{mpz_cdiv_r_ui} the negated remainder is small enough to fit in an
869: @code{unsigned long int}, and it is therefore returned.@refill
870: @end deftypefun
871:
872: @deftypefun void mpz_cdiv_qr (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, mpz_t @var{op2})
873: @deftypefunx {unsigned long int} mpz_cdiv_qr_ui (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, unsigned long int @var{op2})
874: Divide @var{op1} by @var{op2} and put the quotient in @var{rop1} and the
875: remainder in @var{rop2}. The quotient is rounded towards +infinity. Unless
876: the remainder is zero, it has the opposite sign as the divisor.@refill
877:
878: For @code{mpz_cdiv_qr_ui} the negated remainder is small enough to fit in an
879: @code{unsigned long int}, and it is therefore returned.@refill
880:
881: If @var{rop1} and @var{rop2} are the same variable, the results are
882: undefined.@refill
883: @end deftypefun
884:
885: @deftypefun {unsigned long int} mpz_cdiv_ui (mpz_t @var{op1}, unsigned long int @var{op2})
886: Return the negated remainder, similar to @code{mpz_cdiv_r_ui}. (The
887: difference is that this function doesn't store the remainder anywhere.)@refill
888: @end deftypefun
889:
890: @deftypefun void mpz_mod (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
891: @deftypefunx {unsigned long int} mpz_mod_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
892: Set @var{rop} to @var{op1} @code{mod} @var{op2}. The sign of the divisor is
893: ignored, and the result is always non-negative.@refill
894:
895: For @code{mpz_mod_ui} the remainder is small enough to fit in an
896: @code{unsigned long int}, and is therefore returned.@refill
897: @end deftypefun
898:
899: @deftypefun void mpz_divexact (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
900: Set @var{rop} to @var{op1}/@var{op2}. This function produces correct
901: results only when it is known in advance that @var{op2} divides
902: @var{op1}.@refill
903:
904: Since mpz_divexact is much faster than any of the other routines that produce
905: the quotient (@pxref{References} Jebelean), it is the best choice for
906: instances in which exact division is known to occur, such as reducing a
907: rational to lowest terms.@refill
908: @end deftypefun
909:
910: @deftypefun void mpz_tdiv_q_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
911: @ifinfo
912: Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}. The quotient is
913: rounded towards 0.@refill
914: @end ifinfo
915: @iftex
916: @tex
917: Set @var{rop} to $@var{op1}/2^{op2}$. The quotient is rounded towards 0.
918: @end tex
919: @end iftex
920: @end deftypefun
921:
922: @deftypefun void mpz_tdiv_r_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
923: @ifinfo
924: Divide @var{op1} by (2 raised to @var{op2}) and put the remainder in
925: @var{rop}. Unless it is zero, @var{rop} will have the same sign as @var{op1}.@refill
926: @end ifinfo
927: @iftex
928: @tex
929: Divide @var{op1} by $2^{op2}$ and put the remainder in @var{rop}. Unless it is
930: zero, @var{rop} will have the same sign as @var{op1}.
931: @end tex
932: @end iftex
933: @end deftypefun
934:
935: @deftypefun void mpz_fdiv_q_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
936: @ifinfo
937: Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}. The quotient is
938: rounded towards @minus{}infinity.@refill
939: @end ifinfo
940: @iftex
941: @tex
942: Set @var{rop} to $\lfloor@var{op1}/2^{op2}\rfloor$. The quotient is rounded
943: towards $-\infty$.
944: @end tex
945: @end iftex
946: @end deftypefun
947:
948: @deftypefun void mpz_fdiv_r_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
949: @ifinfo
950: Divide @var{op1} by (2 raised to @var{op2}) and put the remainder in
951: @var{rop}. The sign of @var{rop} will always be positive.@refill
952: @end ifinfo
953: @iftex
954: @tex
955: Divide @var{op1} by $2^{op2}$ and put the remainder in @var{rop}. The sign of
956: @var{rop} will always be positive.
957: @end tex
958: @end iftex
959:
960: This operation can also be defined as masking of the @var{op2} least
961: significant bits.@refill
962: @end deftypefun
963:
964: @subsection Exponentialization Functions
965:
966: @deftypefun void mpz_powm (mpz_t @var{rop}, mpz_t @var{base}, mpz_t @var{exp}, mpz_t @var{mod})
967: @deftypefunx void mpz_powm_ui (mpz_t @var{rop}, mpz_t @var{base}, unsigned long int @var{exp}, mpz_t @var{mod})
968: Set @var{rop} to (@var{base} raised to @var{exp}) @code{mod} @var{mod}. If
969: @var{exp} is negative, the result is undefined.@refill
970: @end deftypefun
971:
972: @deftypefun void mpz_pow_ui (mpz_t @var{rop}, mpz_t @var{base}, unsigned long int @var{exp})
973: @deftypefunx void mpz_ui_pow_ui (mpz_t @var{rop}, unsigned long int @var{base}, unsigned long int @var{exp})
974: Set @var{rop} to @var{base} raised to @var{exp}.@refill
975: @ifinfo
976: The case of 0^0 yields 1.@refill
977: @end ifinfo
978: @iftex
979: @tex
980: The case of $0^0$ yields 1.
981: @end tex
982: @end iftex
983: @end deftypefun
984:
985: @subsection Square Root Functions
986:
987: @deftypefun void mpz_sqrt (mpz_t @var{rop}, mpz_t @var{op})
988: @ifinfo
989: Set @var{rop} to the truncated integer part of the square root of
990: @var{op}.@refill
991: @end ifinfo
992: @iftex
993: @tex
994: Set @var{rop} to $\lfloor\sqrt{@var{op}}\rfloor$, the truncated integer
995: part of the square root of @var{op}.
996: @end tex
997: @end iftex
998: @end deftypefun
999:
1000: @deftypefun void mpz_sqrtrem (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op})
1001: @ifinfo
1002: Set @var{rop1} to the truncated integer part of the square root of @var{op},
1003: like @code{mpz_sqrt}. Set @var{rop2} to
1004: @var{op}@minus{}@var{rop1}*@var{rop1},@refill
1005: @end ifinfo
1006: @iftex
1007: @tex
1008: Set @var{rop1} to $\lfloor\sqrt{@var{op}}\rfloor$, like @code{mpz_sqrt}.
1009: Set @var{rop2} to $(@var{op} - @var{rop1}^2)$,
1010: @end tex
1011: @end iftex
1012: (i.e., zero if @var{op} is a perfect square).@refill
1013:
1014: If @var{rop1} and @var{rop2} are the same variable, the results are
1015: undefined.@refill
1016: @end deftypefun
1017:
1018: @deftypefun int mpz_perfect_square_p (mpz_t @var{op})
1019: Return non-zero if @var{op} is a perfect square, i.e., if the square root of
1020: @var{op} is an integer. Return zero otherwise.@refill
1021: @end deftypefun
1022:
1023: @subsection Number Theoretic Functions
1024:
1025: @deftypefun int mpz_probab_prime_p (mpz_t @var{op}, int @var{reps})
1026: @ifinfo
1027: If this function returns 0, @var{op} is definitely not prime. If it returns
1028: 1, then @var{op} is `probably' prime. The probability of a false positive is
1029: (1/4)**@var{reps}.@refill
1030: @end ifinfo
1031: @iftex
1032: @tex
1033: If this function returns 0, @var{op} is definitely not prime. If it returns
1034: 1, then @var{op} is `probably' prime. The probability of a false positive is
1035: $(1/4)^{{reps}}$.
1036: @end tex
1037: @end iftex
1038: A reasonable value of reps is 25.@refill
1039:
1040: An implementation of the probabilistic primality test found in Seminumerical
1041: Algorithms (@pxref{References} Knuth).@refill
1042: @end deftypefun
1043:
1044: @deftypefun void mpz_gcd (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
1045: Set @var{rop} to the greatest common divisor of @var{op1} and @var{op2}.@refill
1046: @end deftypefun
1047:
1048: @deftypefun {unsigned long int} mpz_gcd_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
1049: Compute the greatest common divisor of @var{op1} and @var{op2}. If
1050: @var{rop} is not NULL, store the result there.@refill
1051:
1052: If the result is small enough to fit in an @code{unsigned long int}, it is
1053: returned. If the result does not fit, 0 is returned, and the result is equal
1054: to the argument @var{op1}. Note that the result will always fit if @var{op2}
1055: is non-zero.@refill
1056: @end deftypefun
1057:
1058: @deftypefun void mpz_gcdext (mpz_t @var{g}, mpz_t @var{s}, mpz_t @var{t}, mpz_t @var{a}, mpz_t @var{b})
1059: Compute @var{g}, @var{s}, and @var{t}, such that @var{a}@var{s} +
1060: @var{b}@var{t} = @var{g} = @code{gcd} (@var{a}, @var{b}). If @var{t} is
1061: NULL, that argument is not computed.@refill
1062: @end deftypefun
1063:
1064: @deftypefun int mpz_invert (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
1065: Compute the inverse of @var{op1} modulo @var{op2} and put the result in
1066: @var{rop}. Return non-zero if an inverse exist, zero otherwise. When the
1067: function returns zero, do not assume anything about the value in @var{rop}.@refill
1068: @end deftypefun
1069:
1070: @deftypefun int mpz_jacobi (mpz_t @var{op1}, mpz_t @var{op2})
1071: @deftypefunx int mpz_legendre (mpz_t @var{op1}, mpz_t @var{op2})
1072: Compute the Jacobi and Legendre symbols, respectively.@refill
1073: @end deftypefun
1074:
1075: @need 2000
1076: @node Comparison Functions, Integer Logic and Bit Fiddling, Integer Arithmetic, Integer Functions
1077: @comment node-name, next, previous, up
1078: @section Comparison Functions
1079:
1080: @deftypefun int mpz_cmp (mpz_t @var{op1}, mpz_t @var{op2})
1081: @ifinfo
1082: Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} >
1083: @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
1084: @var{op2}.@refill
1085: @end ifinfo
1086: @iftex
1087: @tex
1088: Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} >
1089: @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
1090: < @var{op2}$.
1091: @end tex
1092: @end iftex
1093: @end deftypefun
1094:
1095: @deftypefn Macro int mpz_cmp_ui (mpz_t @var{op1}, unsigned long int @var{op2})
1096: @deftypefnx Macro int mpz_cmp_si (mpz_t @var{op1}, signed long int @var{op2})
1097: @ifinfo
1098: Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} >
1099: @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
1100: @var{op2}.@refill
1101: @end ifinfo
1102: @iftex
1103: @tex
1104: Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} >
1105: @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
1106: < @var{op2}$.
1107: @end tex
1108: @end iftex
1109:
1110: These functions are actually implemented as macros. They evaluate their
1111: arguments multiple times.@refill
1112: @end deftypefn
1113:
1114: @deftypefn Macro int mpz_sgn (mpz_t @var{op})
1115: @ifinfo
1116: Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0.@refill
1117: @end ifinfo
1118: @iftex
1119: @tex
1120: Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$.
1121: @end tex
1122: @end iftex
1123:
1124: This function is actually implemented as a macro. It evaluates its
1125: arguments multiple times.@refill
1126: @end deftypefn
1127:
1128: @node Integer Logic and Bit Fiddling, I/O of Integers, Comparison Functions, Integer Functions
1129: @comment node-name, next, previous, up
1130: @section Logical and Bit Manipulation Functions
1131: @cindex Logical functions
1132: @cindex Bit manipulation functions
1133:
1134: These functions behave as if two's complement arithmetic were used (although
1135: sign-magnitude is used by the actual implementation).@refill
1136:
1137: @deftypefun void mpz_and (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
1138: Set @var{rop} to @var{op1} logical-and @var{op2}.@refill
1139: @end deftypefun
1140:
1141: @deftypefun void mpz_ior (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
1142: Set @var{rop} to @var{op1} inclusive-or @var{op2}.@refill
1143: @end deftypefun
1144:
1145: @c @deftypefun void mpz_xor (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
1146: @c Set @var{rop} to @var{op1} exclusive-or @var{op2}.
1147: @c @end deftypefun
1148:
1149: @deftypefun void mpz_com (mpz_t @var{rop}, mpz_t @var{op})
1150: Set @var{rop} to the one's complement of @var{op}.@refill
1151: @end deftypefun
1152:
1153: @deftypefun {unsigned long int} mpz_popcount (mpz_t @var{op})
1154: For non-negative numbers, return the population count of @var{op}. For
1155: negative numbers, return the largest possible value (@var{MAX_ULONG}).@refill
1156: @end deftypefun
1157:
1158: @deftypefun {unsigned long int} mpz_hamdist (mpz_t @var{op1}, mpz_t @var{op2})
1159: If @var{op1} and @var{op2} are both non-negative, return the hamming distance
1160: between the two operands. Otherwise, return the largest possible value
1161: (@var{MAX_ULONG}).@refill
1162:
1163: It is possible to extend this function to return a useful value when the
1164: operands are both negative, but the current implementation returns
1165: @var{MAX_ULONG} in this case. @strong{Do not depend on this behavior, since
1166: it will change in future versions of the library.}@refill
1167: @end deftypefun
1168:
1169: @deftypefun {unsigned long int} mpz_scan0 (mpz_t @var{op}, unsigned long int @var{starting_bit})
1170: Scan @var{op}, starting with bit @var{starting_bit}, towards more significant
1171: bits, until the first clear bit is found. Return the index of the found bit.@refill
1172: @end deftypefun
1173:
1174: @deftypefun {unsigned long int} mpz_scan1 (mpz_t @var{op}, unsigned long int @var{starting_bit})
1175: Scan @var{op}, starting with bit @var{starting_bit}, towards more significant
1176: bits, until the first set bit is found. Return the index of the found bit.@refill
1177: @end deftypefun
1178:
1179: @deftypefun void mpz_setbit (mpz_t @var{rop}, unsigned long int @var{bit_index})
1180: Set bit @var{bit_index} in @var{op1}.@refill
1181: @end deftypefun
1182:
1183: @deftypefun void mpz_clrbit (mpz_t @var{rop}, unsigned long int @var{bit_index})
1184: Clear bit @var{bit_index} in @var{op1}.@refill
1185: @end deftypefun
1186:
1187: @node I/O of Integers, Miscellaneous Integer Functions, Integer Logic and Bit Fiddling, Integer Functions
1188: @comment node-name, next, previous, up
1189: @section Input and Output Functions
1190: @cindex Integer input and output functions
1191: @cindex Input functions
1192: @cindex Output functions
1193: @cindex I/O functions
1194:
1195: Functions that perform input from a stdio stream, and functions that output to
1196: a stdio stream. Passing a NULL pointer for a @var{stream} argument to any of
1197: these functions will make them read from @code{stdin} and write to
1198: @code{stdout}, respectively.@refill
1199:
1200: When using any of these functions, it is a good idea to include @file{stdio.h}
1201: before @file{gmp.h}, since that will allow @file{gmp.h} to define prototypes
1202: for these functions.@refill
1203:
1204: @deftypefun size_t mpz_out_str (FILE *@var{stream}, int @var{base}, mpz_t @var{op})
1205: Output @var{op} on stdio stream @var{stream}, as a string of digits in base
1206: @var{base}. The base may vary from 2 to 36.@refill
1207:
1208: Return the number of bytes written, or if an error occurred, return 0.@refill
1209: @end deftypefun
1210:
1211: @deftypefun size_t mpz_inp_str (mpz_t @var{rop}, FILE *@var{stream}, int @var{base})
1212: Input a possibly white-space preceded string in base @var{base} from stdio
1213: stream @var{stream}, and put the read integer in @var{rop}. The base may vary
1214: from 2 to 36. If @var{base} is 0, the actual base is determined from the
1215: leading characters: if the first two characters are `0x' or `0X', hexadecimal
1216: is assumed, otherwise if the first character is `0', octal is assumed,
1217: otherwise decimal is assumed.@refill
1218:
1219: Return the number of bytes read, or if an error occurred, return 0.@refill
1220: @end deftypefun
1221:
1222: @deftypefun size_t mpz_out_raw (FILE *@var{stream}, mpz_t @var{op})
1223: Output @var{op} on stdio stream @var{stream}, in raw binary format. The
1224: integer is written in a portable format, with 4 bytes of size information, and
1225: that many bytes of limbs. Both the size and the limbs are written in
1226: decreasing significance order (i.e., in big-endian).@refill
1227:
1228: The output can be read with @code{mpz_inp_raw}.@refill
1229:
1230: Return the number of bytes written, or if an error occurred, return 0.@refill
1231:
1232: The output of this can not be read by @code{mpz_inp_raw} from GMP 1, because
1233: of changes necessary for compatibility between 32-bit and 64-bit machines.@refill
1234: @end deftypefun
1235:
1236: @deftypefun size_t mpz_inp_raw (mpz_t @var{rop}, FILE *@var{stream})
1237: Input from stdio stream @var{stream} in the format written by
1238: @code{mpz_out_raw}, and put the result in @var{rop}. Return the number of
1239: bytes read, or if an error occurred, return 0.@refill
1240:
1241: This routine can read the output from @code{mpz_out_raw} also from GMP 1, in
1242: spite of changes necessary for compatibility between 32-bit and 64-bit
1243: machines.@refill
1244: @end deftypefun
1245:
1246:
1247: @need 2000
1248: @node Miscellaneous Integer Functions,, I/O of Integers, Integer Functions
1249: @comment node-name, next, previous, up
1250: @section Miscellaneous Functions
1251: @cindex Miscellaneous integer functions
1252:
1253: @deftypefun void mpz_random (mpz_t @var{rop}, mp_size_t @var{max_size})
1254: Generate a random integer of at most @var{max_size} limbs. The generated
1255: random number doesn't satisfy any particular requirements of randomness.
1256: Negative random numbers are generated when @var{max_size} is negative.@refill
1257: @end deftypefun
1258:
1259: @deftypefun void mpz_random2 (mpz_t @var{rop}, mp_size_t @var{max_size})
1260: Generate a random integer of at most @var{max_size} limbs, with long strings
1261: of zeros and ones in the binary representation. Useful for testing functions
1262: and algorithms, since this kind of random numbers have proven to be more
1263: likely to trigger corner-case bugs. Negative random numbers are generated
1264: when @var{max_size} is negative.@refill
1265: @end deftypefun
1266:
1267: @deftypefun size_t mpz_size (mpz_t @var{op})
1268: Return the size of @var{op} measured in number of limbs. If @var{op} is zero,
1269: the returned value will be zero.@refill
1270: @c (@xref{Nomenclature}, for an explanation of the concept @dfn{limb}.)
1271:
1272: @strong{This function is obsolete. It will disappear from future MP
1273: releases.}@refill
1274: @end deftypefun
1275:
1276: @deftypefun size_t mpz_sizeinbase (mpz_t @var{op}, int @var{base})
1277: Return the size of @var{op} measured in number of digits in base @var{base}.
1278: The base may vary from 2 to 36. The returned value will be exact or 1 too
1279: big. If @var{base} is a power of 2, the returned value will always be exact.@refill
1280:
1281: This function is useful in order to allocate the right amount of space before
1282: converting @var{op} to a string. The right amount of allocation is normally
1283: two more than the value returned by @code{mpz_sizeinbase} (one extra for a
1284: minus sign and one for the terminating '\0').@refill
1285: @end deftypefun
1286:
1287:
1288: @node Rational Number Functions, Floating-point Functions, Integer Functions, Top
1289: @comment node-name, next, previous, up
1290: @chapter Rational Number Functions
1291: @cindex Rational number functions
1292:
1293: This chapter describes the MP functions for performing arithmetic on rational
1294: numbers. These functions start with the prefix @code{mpq_}.@refill
1295:
1296: Rational numbers are stored in objects of type @code{mpq_t}.@refill
1297:
1298: All rational arithmetic functions assume operands have a canonical form, and
1299: canonicalize their result. The canonical from means that the denominator and
1300: the numerator have no common factors, and that the denominator is positive.
1301: Zero has the unique representation 0/1.@refill
1302:
1303: Pure assignment functions do not canonicalize the assigned variable. It is
1304: the responsibility of the user to canonicalize the assigned variable before
1305: any arithmetic operations are performed on that variable. @strong{Note that
1306: this is an incompatible change from version 1 of the library.}@refill
1307:
1308: @deftypefun void mpq_canonicalize (mpq_t @var{op})
1309: Remove any factors that are common to the numerator and denominator of
1310: @var{op}, and make the denominator positive.@refill
1311: @end deftypefun
1312:
1313: @menu
1314: * Initializing Rationals::
1315: * Assigning Rationals::
1316: * Simultaneous Integer Init & Assign::
1317: * Comparing Rationals::
1318: * Applying Integer Functions::
1319: * Miscellaneous Rational Functions::
1320: @end menu
1321:
1322: @node Initializing Rationals, Assigning Rationals, Rational Number Functions, Rational Number Functions
1323: @comment node-name, next, previous, up
1324: @section Initialization and Assignment Functions
1325:
1326: @deftypefun void mpq_init (mpq_t @var{dest_rational})
1327: Initialize @var{dest_rational} and set it to 0/1. Each variable should
1328: normally only be initialized once, or at least cleared out (using the function
1329: @code{mpq_clear}) between each initialization.@refill
1330: @end deftypefun
1331:
1332: @deftypefun void mpq_clear (mpq_t @var{rational_number})
1333: Free the space occupied by @var{rational_number}. Make sure to call this
1334: function for all @code{mpq_t} variables when you are done with them.@refill
1335: @end deftypefun
1336:
1337: @deftypefun void mpq_set (mpq_t @var{rop}, mpq_t @var{op})
1338: @deftypefunx void mpq_set_z (mpq_t @var{rop}, mpz_t @var{op})
1339: Assign @var{rop} from @var{op}.@refill
1340: @end deftypefun
1341:
1342: @deftypefun void mpq_set_ui (mpq_t @var{rop}, unsigned long int @var{op1}, unsigned long int @var{op2})
1343: @deftypefunx void mpq_set_si (mpq_t @var{rop}, signed long int @var{op1}, unsigned long int @var{op2})
1344: Set the value of @var{rop} to @var{op1}/@var{op2}. Note that if @var{op1} and
1345: @var{op2} have common factors, @var{rop} has to be passed to
1346: @code{mpq_canonicalize} before any operations are performed on @var{rop}.@refill
1347: @end deftypefun
1348:
1349: @node Assigning Rationals, Comparing Rationals, Initializing Rationals, Rational Number Functions
1350: @comment node-name, next, previous, up
1351: @section Arithmetic Functions
1352:
1353: @deftypefun void mpq_add (mpq_t @var{sum}, mpq_t @var{addend1}, mpq_t @var{addend2})
1354: Set @var{sum} to @var{addend1} + @var{addend2}.@refill
1355: @end deftypefun
1356:
1357: @deftypefun void mpq_sub (mpq_t @var{difference}, mpq_t @var{minuend}, mpq_t @var{subtrahend})
1358: Set @var{difference} to @var{minuend} @minus{} @var{subtrahend}.@refill
1359: @end deftypefun
1360:
1361: @deftypefun void mpq_mul (mpq_t @var{product}, mpq_t @var{multiplier}, mpq_t @var{multiplicand})
1362: @ifinfo
1363: Set @var{product} to @var{multiplier} times @var{multiplicand}.@refill
1364: @end ifinfo
1365: @iftex
1366: @tex
1367: Set @var{product} to $@var{multiplier} \times @var{multiplicand}$.
1368: @end tex
1369: @end iftex
1370: @end deftypefun
1371:
1372: @deftypefun void mpq_div (mpq_t @var{quotient}, mpq_t @var{dividend}, mpq_t @var{divisor})
1373: Set @var{quotient} to @var{dividend}/@var{divisor}.@refill
1374: @end deftypefun
1375:
1376: @deftypefun void mpq_neg (mpq_t @var{negated_operand}, mpq_t @var{operand})
1377: Set @var{negated_operand} to @minus{}@var{operand}.@refill
1378: @end deftypefun
1379:
1380: @deftypefun void mpq_inv (mpq_t @var{inverted_number}, mpq_t @var{number})
1381: Set @var{inverted_number} to 1/@var{number}. If the new denominator is
1382: zero, this routine will divide by zero.@refill
1383: @end deftypefun
1384:
1385: @node Comparing Rationals, Applying Integer Functions, Assigning Rationals, Rational Number Functions
1386: @comment node-name, next, previous, up
1387: @section Comparison Functions
1388:
1389: @deftypefun int mpq_cmp (mpq_t @var{op1}, mpq_t @var{op2})
1390: @ifinfo
1391: Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} >
1392: @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
1393: @var{op2}.@refill
1394: @end ifinfo
1395: @iftex
1396: @tex
1397: Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} >
1398: @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
1399: < @var{op2}$.
1400: @end tex
1401: @end iftex
1402:
1403: To determine if two rationals are equal, @code{mpq_equal} is faster than
1404: @code{mpq_cmp}.@refill
1405: @end deftypefun
1406:
1407: @deftypefn Macro int mpq_cmp_ui (mpq_t @var{op1}, unsigned long int @var{num2}, unsigned long int @var{den2})
1408: @ifinfo
1409: Compare @var{op1} and @var{num2}/@var{den2}. Return a positive value if
1410: @var{op1} > @var{num2}/@var{den2}, zero if @var{op1} = @var{num2}/@var{den2},
1411: and a negative value if @var{op1} < @var{num2}/@var{den2}.@refill
1412: @end ifinfo
1413: @iftex
1414: @tex
1415: Compare @var{op1} and @var{num2}/@var{den2}. Return a positive value if
1416: $@var{op1} > @var{num2}/@var{den2}$, zero if $@var{op1} =
1417: @var{num2}/@var{den2}$, and a negative value if $@var{op1} <
1418: @var{num2}/@var{den2}$.
1419: @end tex
1420: @end iftex
1421:
1422: This routine allows that @var{num2} and @var{den2} have common factors.@refill
1423:
1424: This function is actually implemented as a macro. It evaluates its
1425: arguments multiple times.@refill
1426: @end deftypefn
1427:
1428: @deftypefn Macro int mpq_sgn (mpq_t @var{op})
1429: @ifinfo
1430: Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0.@refill
1431: @end ifinfo
1432: @iftex
1433: @tex
1434: Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$.
1435: @end tex
1436: @end iftex
1437:
1438: This function is actually implemented as a macro. It evaluates its
1439: arguments multiple times.@refill
1440: @end deftypefn
1441:
1442: @deftypefun int mpq_equal (mpq_t @var{op1}, mpq_t @var{op2})
1443: Return non-zero if @var{op1} and @var{op2} are equal, zero if they are
1444: non-equal. Although @code{mpq_cmp} can be used for the same purpose, this
1445: function is much faster.@refill
1446: @end deftypefun
1447:
1448: @node Applying Integer Functions, Miscellaneous Rational Functions, Comparing Rationals, Rational Number Functions
1449: @comment node-name, next, previous, up
1450: @section Applying Integer Functions to Rationals
1451:
1452: The set of @code{mpq} functions is quite small. In particular, there are no
1453: functions for either input or output. But there are two macros that allow us
1454: to apply any @code{mpz} function on the numerator or denominator of a rational
1455: number. If these macros are used to assign to the rational number,
1456: @code{mpq_canonicalize} normally need to be called afterwards.@refill
1457:
1458: @deftypefn Macro mpz_t mpq_numref (mpq_t @var{op})
1459: @deftypefnx Macro mpz_t mpq_denref (mpq_t @var{op})
1460: Return a reference to the numerator and denominator of @var{op}, respectively.
1461: The @code{mpz} functions can be used on the result of these macros.@refill
1462: @end deftypefn
1463:
1464: @need 2000
1465: @node Miscellaneous Rational Functions, , Applying Integer Functions, Rational Number Functions
1466: @comment node-name, next, previous, up
1467: @section Miscellaneous Functions
1468:
1469: @deftypefun double mpq_get_d (mpq_t @var{op})
1470: Convert @var{op} to a double.@refill
1471: @end deftypefun
1472:
1473: These functions assign between either the numerator or denominator of a
1474: rational, and an integer. Instead of using these functions, it is preferable
1475: to use the more general mechanisms @code{mpq_numref} and @code{mpq_denref},
1476: together with @code{mpz_set}.@refill
1477:
1478: @deftypefun void mpq_set_num (mpq_t @var{rational}, mpz_t @var{numerator})
1479: Copy @var{numerator} to the numerator of @var{rational}. When this risks to
1480: make the numerator and denominator of @var{rational} have common factors, you
1481: have to pass @var{rational} to @code{mpq_canonicalize} before any operations
1482: are performed on @var{rational}.@refill
1483:
1484: This function is equivalent to
1485: @code{mpz_set (mpq_numref (@var{rational}), @var{numerator})}.@refill
1486: @end deftypefun
1487:
1488: @deftypefun void mpq_set_den (mpq_t @var{rational}, mpz_t @var{denominator})
1489: Copy @var{denominator} to the denominator of @var{rational}. When this risks
1490: to make the numerator and denominator of @var{rational} have common factors,
1491: or if the denominator might be negative, you have to pass @var{rational} to
1492: @code{mpq_canonicalize} before any operations are performed on @var{rational}.@refill
1493:
1494: @strong{In version 1 of the library, negative denominators were handled by
1495: copying the sign to the numerator. That is no longer done.}@refill
1496:
1497: This function is equivalent to
1498: @code{mpz_set (mpq_denref (@var{rational}), @var{denominators})}.@refill
1499: @end deftypefun
1500:
1501: @deftypefun void mpq_get_num (mpz_t @var{numerator}, mpq_t @var{rational})
1502: Copy the numerator of @var{rational} to the integer @var{numerator}, to
1503: prepare for integer operations on the numerator.@refill
1504:
1505: This function is equivalent to
1506: @code{mpz_set (@var{numerator}, mpq_numref (@var{rational}))}.@refill
1507: @end deftypefun
1508:
1509: @deftypefun void mpq_get_den (mpz_t @var{denominator}, mpq_t @var{rational})
1510: Copy the denominator of @var{rational} to the integer @var{denominator}, to
1511: prepare for integer operations on the denominator.@refill
1512:
1513: This function is equivalent to
1514: @code{mpz_set (@var{denominator}, mpq_denref (@var{rational}))}.@refill
1515: @end deftypefun
1516:
1517:
1518: @node Floating-point Functions, Low-level Functions, Rational Number Functions, Top
1519: @comment node-name, next, previous, up
1520: @chapter Floating-point Functions
1521: @cindex Floating-point functions
1522: @cindex Float functions
1523:
1524: This is a description of the @emph{preliminary} interface for floating-point
1525: arithmetic in GNU MP 2.@refill
1526:
1527: The floating-point functions expect arguments of type @code{mpf_t}.@refill
1528:
1529: The MP floating-point functions have an interface that is similar to the MP
1530: integer functions. The function prefix for floating-point operations is
1531: @code{mpf_}.@refill
1532:
1533: There is one significant characteristic of floating-point numbers that has
1534: motivated a difference between this function class and other MP function
1535: classes: the inherent inexactness of floating point arithmetic. The user has
1536: to specify the precision of each variable. A computation that assigns a
1537: variable will take place with the precision of the assigned variable; the
1538: precision of variables used as input is ignored.@refill
1539:
1540: @cindex User-defined precision
1541: The precision of a calculation is defined as follows: Compute the requested
1542: operation exactly (with "infinite precision"), and truncate the result to
1543: the destination variable precision. Even if the user has asked for a very
1544: high precision, MP will not calculate with superfluous digits. For example,
1545: if two low-precision numbers of nearly equal magnitude are added, the
1546: precision of the result will be limited to what is required to represent the
1547: result accurately.@refill
1548:
1549: The MP floating-point functions are @emph{not} intended as a smooth extension
1550: to the IEEE P754 arithmetic. Specifically, the results obtained on one
1551: computer often differs from the results obtained on a computer with a
1552: different word size.@refill
1553:
1554: @menu
1555: * Initializing Floats::
1556: * Assigning Floats::
1557: * Simultaneous Float Init & Assign::
1558: * Converting Floats::
1559: * Float Arithmetic::
1560: * Float Comparison::
1561: * I/O of Floats::
1562: * Miscellaneous Float Functions::
1563: @end menu
1564:
1565: @node Initializing Floats, Assigning Floats, , Floating-point Functions
1566: @comment node-name, next, previous, up
1567: @section Initialization and Assignment Functions
1568:
1569: @deftypefun void mpf_set_default_prec (unsigned long int @var{prec})
1570: Set the default precision to be @strong{at least} @var{prec} bits. All
1571: subsequent calls to @code{mpf_init} will use this precision, but previously
1572: initialized variables are unaffected.@refill
1573: @end deftypefun
1574:
1575: An @code{mpf_t} object must be initialized before storing the first value in
1576: it. The functions @code{mpf_init} and @code{mpf_init2} are used for that
1577: purpose.@refill
1578:
1579: @deftypefun void mpf_init (mpf_t @var{x})
1580: Initialize @var{x} to 0. Normally, a variable should be initialized once only
1581: or at least be cleared, using @code{mpf_clear}, between initializations. The
1582: precision of @var{x} is undefined unless a default precision has already been
1583: established by a call to @code{mpf_set_default_prec}.@refill
1584: @end deftypefun
1585:
1586: @deftypefun void mpf_init2 (mpf_t @var{x}, unsigned long int @var{prec})
1587: Initialize @var{x} to 0 and set its precision to be @strong{at least}
1588: @var{prec} bits. Normally, a variable should be initialized once only or at
1589: least be cleared, using @code{mpf_clear}, between initializations.@refill
1590: @end deftypefun
1591:
1592: @deftypefun void mpf_clear (mpf_t @var{x})
1593: Free the space occupied by @var{x}. Make sure to call this function for all
1594: @code{mpf_t} variables when you are done with them.@refill
1595: @end deftypefun
1596:
1597: @need 2000
1598: Here is an example on how to initialize floating-point variables:@refill
1599: @example
1600: @{
1601: mpf_t x, y;
1602: mpf_init (x); /* use default precision */
1603: mpf_init2 (y, 256); /* precision @emph{at least} 256 bits */
1604: @dots{}
1605: /* Unless the program is about to exit, do ... */
1606: mpf_clear (x);
1607: mpf_clear (y);
1608: @}
1609: @end example
1610:
1611: The following three functions are useful for changing the precision during a
1612: calculation. A typical use would be for adjusting the precision gradually in
1613: iterative algorithms like Newton-Raphson, making the computation precision
1614: closely match the actual accurate part of the numbers.@refill
1615:
1616: @deftypefun void mpf_set_prec (mpf_t @var{rop}, unsigned long int @var{prec})
1617: Set the precision of @var{rop} to be @strong{at least} @var{prec} bits.
1618: Since changing the precision involves calls to @code{realloc}, this routine
1619: should not be called in a tight loop.@refill
1620: @end deftypefun
1621:
1622: @deftypefun {unsigned long int} mpf_get_prec (mpf_t @var{op})
1623: Return the precision actually used for assignments of @var{op}.@refill
1624: @end deftypefun
1625:
1626: @deftypefun void mpf_set_prec_raw (mpf_t @var{rop}, unsigned long int @var{prec})
1627: Set the precision of @var{rop} to be @strong{at least} @var{prec} bits. This
1628: is a low-level function that does not change the allocation. The @var{prec}
1629: argument must not be larger that the precision previously returned by
1630: @code{mpf_get_prec}. It is crucial that the precision of @var{rop} is
1631: ultimately reset to exactly the value returned by @code{mpf_get_prec}.@refill
1632: @end deftypefun
1633:
1634:
1635: @node Assigning Floats, Simultaneous Float Init & Assign, Initializing Floats, Floating-point Functions
1636: @comment node-name, next, previous, up
1637: @subsection Assignment Functions
1638: @cindex Float assignment functions
1639:
1640: These functions assign new values to already initialized floats
1641: (@pxref{Initializing Floats}).@refill
1642:
1643: @deftypefun void mpf_set (mpf_t @var{rop}, mpf_t @var{op})
1644: @deftypefunx void mpf_set_ui (mpf_t @var{rop}, unsigned long int @var{op})
1645: @deftypefunx void mpf_set_si (mpf_t @var{rop}, signed long int @var{op})
1646: @deftypefunx void mpf_set_d (mpf_t @var{rop}, double @var{op})
1647: @deftypefunx void mpf_set_z (mpf_t @var{rop}, mpz_t @var{op})
1648: @deftypefunx void mpf_set_q (mpf_t @var{rop}, mpq_t @var{op})
1649: Set the value of @var{rop} from @var{op}.@refill
1650: @end deftypefun
1651:
1652: @deftypefun int mpf_set_str (mpf_t @var{rop}, char *@var{str}, int @var{base})
1653: Set the value of @var{rop} from the string in @var{str}. The string is of the
1654: form @samp{M@@N} or, if the base is 10 or less, alternatively @samp{MeN}.
1655: @samp{M} is the mantissa and @samp{N} is the exponent. The mantissa is always
1656: in the specified base. The exponent is either in the specified base or, if
1657: @var{base} is negative, in decimal.@refill
1658:
1659: The argument @var{base} may be in the ranges 2 to 36, or @minus{}36 to
1660: @minus{}2. Negative values are used to specify that the exponent is in
1661: decimal.@refill
1662:
1663: Unlike the corresponding @code{mpz} function, the base will not be determined
1664: from the leading characters of the string if @var{base} is 0. This is so that
1665: numbers like @samp{0.23} are not interpreted as octal.@refill
1666:
1667: White space is allowed in the string, and is simply ignored.@refill
1668:
1669: This function returns 0 if the entire string up to the '\0' is a valid number
1670: in base @var{base}. Otherwise it returns @minus{}1.@refill
1671: @end deftypefun
1672:
1673:
1674: @node Simultaneous Float Init & Assign, Converting Floats, Assigning Floats, Floating-point Functions
1675: @comment node-name, next, previous, up
1676: @subsection Combined Initialization and Assignment Functions
1677: @cindex Initialization and assignment functions
1678:
1679: For convenience, MP provides a parallel series of initialize-and-set functions
1680: which initialize the output and then store the value there. These functions'
1681: names have the form @code{mpf_init_set@dots{}}@refill
1682:
1683: Once the float has been initialized by any of the @code{mpf_init_set@dots{}}
1684: functions, it can be used as the source or destination operand for the ordinary
1685: float functions. Don't use an initialize-and-set function on a variable
1686: already initialized!@refill
1687:
1688: @deftypefun void mpf_init_set (mpf_t @var{rop}, mpf_t @var{op})
1689: @deftypefunx void mpf_init_set_ui (mpf_t @var{rop}, unsigned long int @var{op})
1690: @deftypefunx void mpf_init_set_si (mpf_t @var{rop}, signed long int @var{op})
1691: @deftypefunx void mpf_init_set_d (mpf_t @var{rop}, double @var{op})
1692: Initialize @var{rop} and set its value from @var{op}.@refill
1693:
1694: The precision of @var{rop} will be taken from the active default precision, as
1695: set by @code{mpf_set_default_prec}.@refill
1696: @end deftypefun
1697:
1698: @deftypefun int mpf_init_set_str (mpf_t @var{rop}, char *@var{str}, int @var{base})
1699: Initialize @var{rop} and set its value from the string in @var{str}. See
1700: @code{mpf_set_str} above for details on the assignment operation.@refill
1701:
1702: Note that @var{rop} is initialized even if an error occurs. (I.e., you have to
1703: call @code{mpf_clear} for it.)@refill
1704:
1705: The precision of @var{rop} will be taken from the active default precision, as
1706: set by @code{mpf_set_default_prec}.@refill
1707: @end deftypefun
1708:
1709:
1710: @node Converting Floats, Float Arithmetic, Simultaneous Float Init & Assign, Floating-point Functions
1711: @comment node-name, next, previous, up
1712: @section Conversion Functions
1713: @cindex Conversion functions
1714:
1715: @deftypefun double mpf_get_d (mpf_t @var{op})
1716: Convert @var{op} to a double.@refill
1717: @end deftypefun
1718:
1719: @deftypefun {char *} mpf_get_str (char *@var{str}, mp_exp_t *@var{expptr}, int @var{base}, size_t @var{n_digits}, mpf_t @var{op})
1720: Convert @var{op} to a string of digits in base @var{base}. The base may vary
1721: from 2 to 36. Generate at most @var{n_digits} significant digits, or if
1722: @var{n_digits} is 0, the maximum number of digits accurately representable by
1723: @var{op}.@refill
1724:
1725: If @var{str} is NULL, space for the mantissa is allocated using the default
1726: allocation function, and a pointer to the string is returned.@refill
1727:
1728: If @var{str} is not NULL, it should point to a block of storage enough large
1729: for the mantissa, i.e., @var{n_digits} + 2. The two extra bytes are for a
1730: possible minus sign, and for the terminating null character.@refill
1731:
1732: The exponent is written through the pointer @var{expptr}.@refill
1733:
1734: If @var{n_digits} is 0, the maximum number of digits meaningfully achievable
1735: from the precision of @var{op} will be generated. Note that the space
1736: requirements for @var{str} in this case will be impossible for the user to
1737: predetermine. Therefore, you need to pass NULL for the string argument
1738: whenever @var{n_digits} is 0.@refill
1739:
1740: The generated string is a fraction, with an implicit radix point immediately
1741: to the left of the first digit. For example, the number 3.1416 would be
1742: returned as "31416" in the string and 1 written at @var{expptr}.@refill
1743: @end deftypefun
1744:
1745:
1746: @node Float Arithmetic, Float Comparison, Converting Floats, Floating-point Functions
1747: @comment node-name, next, previous, up
1748: @section Arithmetic Functions
1749: @cindex Float arithmetic functions
1750: @cindex Arithmetic functions
1751:
1752: @deftypefun void mpf_add (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
1753: @deftypefunx void mpf_add_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
1754: @ifinfo
1755: Set @var{rop} to @var{op1} + @var{op2}.@refill
1756: @end ifinfo
1757: @iftex
1758: @tex
1759: Set @var{rop} to $@var{op1} + @var{op2}$.
1760: @end tex
1761: @end iftex
1762: @end deftypefun
1763:
1764: @deftypefun void mpf_sub (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
1765: @deftypefunx void mpf_ui_sub (mpf_t @var{rop}, unsigned long int @var{op1}, mpf_t @var{op2})
1766: @deftypefunx void mpf_sub_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
1767: Set @var{rop} to @var{op1} @minus{} @var{op2}.@refill
1768: @end deftypefun
1769:
1770: @deftypefun void mpf_mul (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
1771: @deftypefunx void mpf_mul_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
1772: @ifinfo
1773: Set @var{rop} to @var{op1} times @var{op2}.@refill
1774: @end ifinfo
1775: @iftex
1776: @tex
1777: Set @var{rop} to $@var{op1} \times @var{op2}$.
1778: @end tex
1779: @end iftex
1780: @end deftypefun
1781:
1782: Division is undefined if the divisor is zero, and passing a zero divisor to
1783: the divide functions will make these functions intentionally divide by zero.
1784: This gives the user the possibility to handle arithmetic exceptions in these
1785: functions in the same manner as other arithmetic exceptions.@refill
1786:
1787: @deftypefun void mpf_div (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
1788: @deftypefunx void mpf_ui_div (mpf_t @var{rop}, unsigned long int @var{op1}, mpf_t @var{op2})
1789: @deftypefunx void mpf_div_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
1790: Set @var{rop} to @var{op1}/@var{op2}.@refill
1791: @end deftypefun
1792:
1793: @deftypefun void mpf_sqrt (mpf_t @var{rop}, mpf_t @var{op})
1794: @deftypefunx void mpf_sqrt_ui (mpf_t @var{rop}, unsigned long int @var{op})
1795: @ifinfo
1796: Set @var{rop} to the square root of @var{op}.@refill
1797: @end ifinfo
1798: @iftex
1799: @tex
1800: Set @var{rop} to $\sqrt{@var{op}}$.
1801: @end tex
1802: @end iftex
1803: @end deftypefun
1804:
1805: @c @deftypefun void mpf_pow_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
1806: @c Set @var{rop} to @var{op1} raised to @var{op2}.
1807: @c @end deftypefun
1808:
1809: @deftypefun void mpf_neg (mpf_t @var{rop}, mpf_t @var{op})
1810: Set @var{rop} to @minus{}@var{op}.@refill
1811: @end deftypefun
1812:
1813: @deftypefun void mpf_abs (mpf_t @var{rop}, mpf_t @var{op})
1814: Set @var{rop} to the absolute value of @var{op}.@refill
1815: @end deftypefun
1816:
1817: @deftypefun void mpf_mul_2exp (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
1818: @ifinfo
1819: Set @var{rop} to @var{op1} times 2 raised to @var{op2}.@refill
1820: @end ifinfo
1821: @iftex
1822: @tex
1823: Set @var{rop} to $@var{op1} \times 2^{op2}$.
1824: @end tex
1825: @end iftex
1826: @end deftypefun
1827:
1828: @deftypefun void mpf_div_2exp (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
1829: @ifinfo
1830: Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}.@refill
1831: @end ifinfo
1832: @iftex
1833: @tex
1834: Set @var{rop} to $@var{op1}/2^{op2}$.
1835: @end tex
1836: @end iftex
1837: @end deftypefun
1838:
1839: @node Float Comparison, I/O of Floats, Float Arithmetic, Floating-point Functions
1840: @comment node-name, next, previous, up
1841: @section Comparison Functions
1842: @cindex Float comparisons functions
1843: @cindex Comparison functions
1844:
1845: @deftypefun int mpf_cmp (mpf_t @var{op1}, mpf_t @var{op2})
1846: @deftypefunx int mpf_cmp_ui (mpf_t @var{op1}, unsigned long int @var{op2})
1847: @deftypefunx int mpf_cmp_si (mpf_t @var{op1}, signed long int @var{op2})
1848: @ifinfo
1849: Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} >
1850: @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
1851: @var{op2}.@refill
1852: @end ifinfo
1853: @iftex
1854: @tex
1855: Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} >
1856: @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
1857: < @var{op2}$.
1858: @end tex
1859: @end iftex
1860: @end deftypefun
1861:
1862: @deftypefun int mpf_eq (mpf_t @var{op1}, mpf_t @var{op2}, unsigned long int op3)
1863: Return non-zero if the first @var{op3} bits of @var{op1} and @var{op2} are
1864: equal, zero otherwise. I.e., test of @var{op1} and @var{op2} are
1865: approximately equal.@refill
1866: @end deftypefun
1867:
1868: @deftypefun void mpf_reldiff (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
1869: Compute the relative difference between @var{op1} and @var{op2} and store the
1870: result in @var{rop}.@refill
1871: @end deftypefun
1872:
1873: @deftypefn Macro int mpf_sgn (mpf_t @var{op})
1874: @ifinfo
1875: Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0.@refill
1876: @end ifinfo
1877: @iftex
1878: @tex
1879: Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$.
1880: @end tex
1881: @end iftex
1882:
1883: This function is actually implemented as a macro. It evaluates its
1884: arguments multiple times.@refill
1885: @end deftypefn
1886:
1887: @node I/O of Floats, Miscellaneous Float Functions, Float Comparison, Floating-point Functions
1888: @comment node-name, next, previous, up
1889: @section Input and Output Functions
1890: @cindex Float input and output functions
1891: @cindex Input functions
1892: @cindex Output functions
1893: @cindex I/O functions
1894:
1895: Functions that perform input from a stdio stream, and functions that output to
1896: a stdio stream. Passing a NULL pointer for a @var{stream} argument to any of
1897: these functions will make them read from @code{stdin} and write to
1898: @code{stdout}, respectively.@refill
1899:
1900: When using any of these functions, it is a good idea to include @file{stdio.h}
1901: before @file{gmp.h}, since that will allow @file{gmp.h} to define prototypes
1902: for these functions.@refill
1903:
1904: @deftypefun size_t mpf_out_str (FILE *@var{stream}, int @var{base}, size_t @var{n_digits}, mpf_t @var{op})
1905: Output @var{op} on stdio stream @var{stream}, as a string of digits in
1906: base @var{base}. The base may vary from 2 to 36. Print at most
1907: @var{n_digits} significant digits, or if @var{n_digits} is 0, the maximum
1908: number of digits accurately representable by @var{op}.@refill
1909:
1910: In addition to the significant digits, a leading @samp{0.} and a
1911: trailing exponent, in the form @samp{eNNN}, are printed. If @var{base}
1912: is greater than 10, @samp{@@} will be used instead of @samp{e} as
1913: exponent delimiter.@refill
1914:
1915: Return the number of bytes written, or if an error occurred, return 0.@refill
1916: @end deftypefun
1917:
1918: @deftypefun size_t mpf_inp_str (mpf_t @var{rop}, FILE *@var{stream}, int @var{base})
1919: Input a string in base @var{base} from stdio stream @var{stream}, and put the
1920: read float in @var{rop}. The string is of the form @samp{M@@N} or, if the
1921: base is 10 or less, alternatively @samp{MeN}. @samp{M} is the mantissa and
1922: @samp{N} is the exponent. The mantissa is always in the specified base. The
1923: exponent is either in the specified base or, if @var{base} is negative, in
1924: decimal.@refill
1925:
1926: The argument @var{base} may be in the ranges 2 to 36, or @minus{}36 to
1927: @minus{}2. Negative values are used to specify that the exponent is in
1928: decimal.@refill
1929:
1930: Unlike the corresponding @code{mpz} function, the base will not be determined
1931: from the leading characters of the string if @var{base} is 0. This is so that
1932: numbers like @samp{0.23} are not interpreted as octal.@refill
1933:
1934: Return the number of bytes read, or if an error occurred, return 0.@refill
1935: @end deftypefun
1936:
1937: @c @deftypefun void mpf_out_raw (FILE *@var{stream}, mpf_t @var{float})
1938: @c Output @var{float} on stdio stream @var{stream}, in raw binary
1939: @c format. The float is written in a portable format, with 4 bytes of
1940: @c size information, and that many bytes of limbs. Both the size and the
1941: @c limbs are written in decreasing significance order.
1942: @c @end deftypefun
1943:
1944: @c @deftypefun void mpf_inp_raw (mpf_t @var{float}, FILE *@var{stream})
1945: @c Input from stdio stream @var{stream} in the format written by
1946: @c @code{mpf_out_raw}, and put the result in @var{float}.
1947: @c @end deftypefun
1948:
1949:
1950: @node Miscellaneous Float Functions, , I/O of Floats, Floating-point Functions
1951: @comment node-name, next, previous, up
1952: @section Miscellaneous Functions
1953: @cindex Miscellaneous float functions
1954:
1955: @deftypefun void mpf_random2 (mpf_t @var{rop}, mp_size_t @var{max_size}, mp_exp_t @var{max_exp})
1956: Generate a random float of at most @var{max_size} limbs, with long strings of
1957: zeros and ones in the binary representation. The exponent of the number is in
1958: the interval @minus{}@var{exp} to @var{exp}. This function is useful for
1959: testing functions and algorithms, since this kind of random numbers have
1960: proven to be more likely to trigger corner-case bugs. Negative random numbers
1961: are generated when @var{max_size} is negative.@refill
1962: @end deftypefun
1963:
1964: @c @deftypefun size_t mpf_size (mpf_t @var{op})
1965: @c Return the size of @var{op} measured in number of limbs. If @var{op} is
1966: @c zero, the returned value will be zero. (@xref{Nomenclature}, for an
1967: @c explanation of the concept @dfn{limb}.)
1968: @c
1969: @c @strong{This function is obsolete. It will disappear from future MP
1970: @c releases.}
1971: @c @end deftypefun
1972:
1973: @node Low-level Functions, BSD Compatible Functions, Floating-point Functions, Top
1974: @comment node-name, next, previous, up
1975: @chapter Low-level Functions
1976: @cindex Low-level functions
1977:
1978: This chapter describes low-level MP functions, used to implement the high-level
1979: MP functions, but also intended for time-critical user code.@refill
1980:
1981: These functions start with the prefix @code{mpn_}.@refill
1982:
1983: @c 1. Some of these function clobber input operands.
1984: @c
1985:
1986: The @code{mpn} functions are designed to be as fast as possible, @strong{not}
1987: to provide a coherent calling interface. The different functions have somewhat
1988: similar interfaces, but there are variations that make them hard to use. These
1989: functions do as little as possible apart from the real multiple precision
1990: computation, so that no time is spent on things that not all callers need.@refill
1991:
1992: A source operand is specified by a pointer to the least significant limb and a
1993: limb count. A destination operand is specified by just a pointer. It is the
1994: responsibility of the caller to ensure that the destination has enough space
1995: for storing the result.@refill
1996:
1997: With this way of specifying operands, it is possible to perform computations
1998: on subranges of an argument, and store the result into a subrange of a
1999: destination.@refill
2000:
2001: A common requirement for all functions is that each source area needs at least
2002: one limb. No size argument may be zero.@refill
2003:
2004: The @code{mpn} functions is the base for the implementation of the @code{mpz_},
2005: @code{mpf_}, and @code{mpq_} functions.@refill
2006:
2007: This example adds the number beginning at @var{src1_ptr} and the number
2008: beginning at @var{src2_ptr} and writes the sum at @var{dest_ptr}. All areas
2009: have @var{size} limbs.@refill
2010:
2011: @example
2012: cy = mpn_add_n (dest_ptr, src1_ptr, src2_ptr, size)
2013: @end example
2014:
2015: @noindent
2016: In the notation used here, a source operand is identified by the pointer to
2017: the least significant limb, and the limb count in braces. For example,
2018: @{s1_ptr, s1_size@}.@refill
2019:
2020: @deftypefun mp_limb_t mpn_add_n (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{size})
2021: Add @{@var{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@}, and
2022: write the @var{size} least significant limbs of the result to @var{dest_ptr}.
2023: Return carry, either 0 or 1.@refill
2024:
2025: This is the lowest-level function for addition. It is the preferred function
2026: for addition, since it is written in assembly for most targets. For addition
2027: of a variable to itself (i.e., @var{src1_ptr} equals @var{src2_ptr}, use
2028: @code{mpn_lshift} with a count of 1 for optimal speed.@refill
2029: @end deftypefun
2030:
2031: @deftypefun mp_limb_t mpn_add_1 (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{size}, mp_limb_t @var{src2_limb})
2032: Add @{@var{src1_ptr}, @var{size}@} and @var{src2_limb}, and write the
2033: @var{size} least significant limbs of the result to @var{dest_ptr}. Return
2034: carry, either 0 or 1.@refill
2035: @end deftypefun
2036:
2037: @deftypefun mp_limb_t mpn_add (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{src1_size}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{src2_size})
2038: Add @{@var{src1_ptr}, @var{src1_size}@} and @{@var{src2_ptr},
2039: @var{src2_size}@}, and write the @var{src1_size} least significant limbs of
2040: the result to @var{dest_ptr}. Return carry, either 0 or 1.@refill
2041:
2042: This function requires that @var{src1_size} is greater than or equal to
2043: @var{src2_size}.@refill
2044: @end deftypefun
2045:
2046: @deftypefun mp_limb_t mpn_sub_n (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{size})
2047: Subtract @{@var{src2_ptr}, @var{src2_size}@} from @{@var{src1_ptr},
2048: @var{size}@}, and write the @var{size} least significant limbs of the result
2049: to @var{dest_ptr}. Return borrow, either 0 or 1.@refill
2050:
2051: This is the lowest-level function for subtraction. It is the preferred
2052: function for subtraction, since it is written in assembly for most targets.@refill
2053: @end deftypefun
2054:
2055: @deftypefun mp_limb_t mpn_sub_1 (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{size}, mp_limb_t @var{src2_limb})
2056: Subtract @var{src2_limb} from @{@var{src1_ptr}, @var{size}@}, and write the
2057: @var{size} least significant limbs of the result to @var{dest_ptr}. Return
2058: borrow, either 0 or 1.@refill
2059: @end deftypefun
2060:
2061: @deftypefun mp_limb_t mpn_sub (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{src1_size}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{src2_size})
2062: Subtract @{@var{src2_ptr}, @var{src2_size}@} from @{@var{src1_ptr},
2063: @var{src1_size}@}, and write the @var{src1_size} least significant limbs of
2064: the result to @var{dest_ptr}. Return borrow, either 0 or 1.@refill
2065:
2066: This function requires that @var{src1_size} is greater than or equal to
2067: @var{src2_size}.@refill
2068: @end deftypefun
2069:
2070: @deftypefun void mpn_mul_n (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{size})
2071: Multiply @{@var{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@},
2072: and write the @strong{entire} result to @var{dest_ptr}.@refill
2073:
2074: The destination has to have space for 2@var{size} limbs, even if the
2075: significant result might be one limb smaller.@refill
2076: @end deftypefun
2077:
2078: @deftypefun mp_limb_t mpn_mul_1 (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{size}, mp_limb_t @var{src2_limb})
2079: Multiply @{@var{src1_ptr}, @var{size}@} and @var{src2_limb}, and write the
2080: @var{size} least significant limbs of the product to @var{dest_ptr}. Return
2081: the most significant limb of the product.@refill
2082:
2083: This is a low-level function that is a building block for general
2084: multiplication as well as other operations in MP. It is written in assembly
2085: for most targets.@refill
2086:
2087: Don't call this function if @var{src2_limb} is a power of 2; use
2088: @code{mpn_lshift} with a count equal to the logarithm of @var{src2_limb}
2089: instead, for optimal speed.@refill
2090: @end deftypefun
2091:
2092: @deftypefun mp_limb_t mpn_addmul_1 (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{size}, mp_limb_t @var{src2_limb})
2093: Multiply @{@var{src1_ptr}, @var{size}@} and @var{src2_limb}, and add the
2094: @var{size} least significant limbs of the product to @{@var{dest_ptr},
2095: @var{size}@} and write the result to @var{dest_ptr} @var{dest_ptr}. Return
2096: the most significant limb of the product, plus carry-out from the addition.@refill
2097:
2098: This is a low-level function that is a building block for general
2099: multiplication as well as other operations in MP. It is written in assembly
2100: for most targets.@refill
2101: @end deftypefun
2102:
2103: @deftypefun mp_limb_t mpn_submul_1 (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{size}, mp_limb_t @var{src2_limb})
2104: Multiply @{@var{src1_ptr}, @var{size}@} and @var{src2_limb}, and subtract the
2105: @var{size} least significant limbs of the product from @{@var{dest_ptr},
2106: @var{size}@} and write the result to @var{dest_ptr}. Return the most
2107: significant limb of the product, minus borrow-out from the subtraction.@refill
2108:
2109: This is a low-level function that is a building block for general
2110: multiplication and division as well as other operations in MP. It is written
2111: in assembly for most targets.@refill
2112: @end deftypefun
2113:
2114: @deftypefun mp_limb_t mpn_mul (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{src1_size}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{src2_size})
2115: Multiply @{@var{src1_ptr}, @var{src1_size}@} and @{@var{src2_ptr},
2116: @var{src2_size}@}, and write the result to @var{dest_ptr}. Return the most
2117: significant limb of the result.@refill
2118:
2119: The destination has to have space for @var{src1_size} + @var{src1_size}
2120: limbs, even if the result might be one limb smaller.@refill
2121:
2122: This function requires that @var{src1_size} is greater than or equal to
2123: @var{src2_size}. The destination must be distinct from either input operands.@refill
2124: @end deftypefun
2125:
2126: @deftypefun mp_size_t mpn_divrem (mp_limb_t * @var{r1p}, mp_size_t @var{xsize}, mp_limb_t * @var{rs2p}, mp_size_t @var{rs2size}, const mp_limb_t * @var{s3p}, mp_size_t @var{s3size})
2127: Divide @{@var{rs2p}, @var{rs2size}@} by @{@var{s3p}, @var{s3size}@}, and
2128: write the quotient at @var{r1p}, with the exception of the most significant
2129: limb, which is returned. The remainder replaces the dividend at @var{rs2p}.@refill
2130:
2131: In addition to an integer quotient, @var{xsize} fraction limbs are developed,
2132: and stored after the integral limbs. For most usages, @var{xsize} will be
2133: zero.@refill
2134:
2135: It is required that @var{rs2size} is greater than or equal to @var{s3size}.
2136: It is required that the most significant bit of the divisor is set.@refill
2137:
2138: If the quotient is not needed, pass @var{rs2p} + @var{s3size} as @var{r1p}.
2139: Aside from that special case, no overlap between arguments is permitted.@refill
2140:
2141: Return the most significant limb of the quotient, either 0 or 1.@refill
2142:
2143: The area at @var{r1p} needs to be @var{rs2size} @minus{} @var{s3size} +
2144: @var{xsize} limbs large.@refill
2145: @end deftypefun
2146:
2147: @deftypefun mp_limb_t mpn_divrem_1 (mp_limb_t * @var{r1p}, mp_size_t @var{xsize}, mp_limb_t * @var{s2p}, mp_size_t @var{s2size}, mp_limb_t @var{s3limb})
2148: Divide @{@var{s2p}, @var{s2size}@} by @var{s3limb}, and write the quotient
2149: at @var{r1p}. Return the remainder.@refill
2150:
2151: In addition to an integer quotient, @var{xsize} fraction limbs are developed,
2152: and stored after the integral limbs. For most usages, @var{xsize} will be
2153: zero.@refill
2154:
2155: The areas at @var{r1p} and @var{s2p} have to be identical or completely
2156: separate, not partially overlapping.@refill
2157: @end deftypefun
2158:
2159: @deftypefun mp_size_t mpn_divmod (mp_limb_t * @var{r1p}, mp_limb_t * @var{rs2p}, mp_size_t @var{rs2size}, const mp_limb_t * @var{s3p}, mp_size_t @var{s3size})
2160: @strong{This interface is obsolete. It will disappear from future releases.
2161: Use @code{mpn_divrem} in its stead.}@refill
2162: @end deftypefun
2163:
2164: @deftypefun mp_limb_t mpn_divmod_1 (mp_limb_t * @var{r1p}, mp_limb_t * @var{s2p}, mp_size_t @var{s2size}, mp_limb_t @var{s3limb})
2165: @strong{This interface is obsolete. It will disappear from future releases.
2166: Use @code{mpn_divrem_1} in its stead.}@refill
2167: @end deftypefun
2168:
2169: @deftypefun mp_limb_t mpn_mod_1 (mp_limb_t * @var{s1p}, mp_size_t @var{s1size}, mp_limb_t @var{s2limb})
2170: Divide @{@var{s1p}, @var{s1size}@} by @var{s2limb}, and return the remainder.@refill
2171: @end deftypefun
2172:
2173: @deftypefun mp_limb_t mpn_preinv_mod_1 (mp_limb_t * @var{s1p}, mp_size_t @var{s1size}, mp_limb_t @var{s2limb}, mp_limb_t @var{s3limb})
2174: @strong{This interface is obsolete. It will disappear from future releases.
2175: Use @code{mpn_mod_1} in its stead.}@refill
2176: @end deftypefun
2177:
2178: @deftypefun mp_limb_t mpn_bdivmod (mp_limb_t * @var{dest_ptr}, mp_limb_t * @var{s1p}, mp_size_t @var{s1size}, const mp_limb_t * @var{s2p}, mp_size_t @var{s2size}, unsigned long int @var{d})
2179: The function puts the low [@var{d}/@var{BITS_PER_MP_LIMB}] limbs of
2180: @var{q} =
2181: @{@var{s1p}, @var{s1size}@}/@{@var{s2p}, @var{s2size}@}
2182: mod 2^@var{d}
2183: at @var{dest_ptr},
2184: and returns the high @var{d} mod @var{BITS_PER_MP_LIMB} bits of @var{q}.@refill
2185:
2186: @{@var{s1p}, @var{s1size}@} - @var{q} * @{@var{s2p}, @var{s2size}@}
2187: mod 2^(@var{s1size}*@var{BITS_PER_MP_LIMB})
2188: is placed at @var{s1p}.
2189: Since the low [@var{d}/@var{BITS_PER_MP_LIMB}] limbs of
2190: this difference are zero, it is possible to overwrite the low limbs at
2191: @var{s1p} with this difference,
2192: provided @var{dest_ptr} <= @var{s1p}.@refill
2193:
2194: This function requires that @var{s1size} * @var{BITS_PER_MP_LIMB} >= @var{D},
2195: and that @{@var{s2p}, @var{s2size}@} is odd.@refill
2196:
2197: @strong{This interface is preliminary. It might change incompatibly in
2198: future revisions.}@refill
2199: @end deftypefun
2200:
2201: @deftypefun mp_limb_t mpn_lshift (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src_ptr}, mp_size_t @var{src_size}, unsigned long int @var{count})
2202: Shift @{@var{src_ptr}, @var{src_size}@} @var{count} bits to the left, and
2203: write the @var{src_size} least significant limbs of the result to
2204: @var{dest_ptr}. @var{count} might be in the range 1 to n @minus{} 1, on an
2205: n-bit machine. The bits shifted out to the left are returned.@refill
2206:
2207: Overlapping of the destination space and the source space is allowed in this
2208: function, provided @var{dest_ptr} >= @var{src_ptr}.@refill
2209:
2210: This function is written in assembly for most targets.@refill
2211: @end deftypefun
2212:
2213: @deftypefun mp_limp_t mpn_rshift (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src_ptr}, mp_size_t @var{src_size}, unsigned long int @var{count})
2214: Shift @{@var{src_ptr}, @var{src_size}@} @var{count} bits to the right, and
2215: write the @var{src_size} most significant limbs of the result to
2216: @var{dest_ptr}. @var{count} might be in the range 1 to n @minus{} 1, on an
2217: n-bit machine. The bits shifted out to the right are returned.@refill
2218:
2219: Overlapping of the destination space and the source space is allowed in this
2220: function, provided @var{dest_ptr} <= @var{src_ptr}.@refill
2221:
2222: This function is written in assembly for most targets.@refill
2223: @end deftypefun
2224:
2225: @deftypefun int mpn_cmp (const mp_limb_t * @var{src1_ptr}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{size})
2226: Compare @{@var{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@} and
2227: return a positive value if src1 > src2, 0 of they are equal, and a negative
2228: value if src1 < src2.@refill
2229: @end deftypefun
2230:
2231: @deftypefun mp_size_t mpn_gcd (mp_limb_t * @var{dest_ptr}, mp_limb_t * @var{src1_ptr}, mp_size_t @var{src1_size}, mp_limb_t * @var{src2_ptr}, mp_size_t @var{src2_size})
2232: Puts at @var{dest_ptr} the greatest common divisor of @{@var{src1_ptr},
2233: @var{src1_size}@} and @{@var{src2_ptr}, @var{src2_size}@}; both source
2234: operands are destroyed by the operation. The size in limbs of the greatest
2235: common divisor is returned.@refill
2236:
2237: @{@var{src1_ptr}, @var{src1_size}@} must be odd, and @{@var{src2_ptr},
2238: @var{src2_size}@} must have at least as many bits as @{@var{src1_ptr},
2239: @var{src1_size}@}.@refill
2240:
2241: @strong{This interface is preliminary. It might change incompatibly in
2242: future revisions.}@refill
2243: @end deftypefun
2244:
2245: @deftypefun mp_limb_t mpn_gcd_1 (const mp_limb_t * @var{src1_ptr}, mp_size_t @var{src1_size}, mp_limb_t @var{src2_limb})
2246: Return the greatest common divisor of @{@var{src1_ptr}, @var{src1_size}@}
2247: and @var{src2_limb}, where @var{src2_limb} (as well as @var{src1_size})
2248: must be different from 0.@refill
2249: @end deftypefun
2250:
2251: @deftypefun mp_size_t mpn_gcdext (mp_limb_t * @var{r1p}, mp_limb_t * @var{r2p}, mp_limb_t * @var{s1p}, mp_size_t @var{s1size}, mp_limb_t * @var{s2p}, mp_size_t @var{s2size})
2252: Puts at @var{r1p} the greatest common divisor of @{@var{s1p}, @var{s1size}@}
2253: and @{@var{s2p}, @var{s2size}@}. The first cofactor is written at
2254: @var{r2p}. Both source operands are destroyed by the operation. The size
2255: in limbs of the greatest common divisor is returned.@refill
2256:
2257: @strong{This interface is preliminary. It might change incompatibly in
2258: future revisions.}@refill
2259: @end deftypefun
2260:
2261: @deftypefun mp_size_t mpn_sqrtrem (mp_limb_t * @var{r1p}, mp_limb_t * @var{r2p}, const mp_limb_t * @var{sp}, mp_size_t @var{size})
2262: Compute the square root of @{@var{sp}, @var{size}@} and put the result at
2263: @var{r1p}. Write the remainder at @var{r2p}, unless @var{r2p} is NULL.@refill
2264:
2265: Return the size of the remainder, whether @var{r2p} was NULL or non-NULL.
2266: Iff the operand was a perfect square, the return value will be 0.@refill
2267:
2268: The areas at @var{r1p} and @var{sp} have to be distinct. The areas at
2269: @var{r2p} and @var{sp} have to be identical or completely separate, not
2270: partially overlapping.@refill
2271:
2272: @ifinfo
2273: The area at @var{r1p} needs to have space for ceil(@var{size}/2) limbs.@refill
2274: @end ifinfo
2275: @iftex
2276: @tex
2277: The area at @var{r1p} needs to have space for $\lceil@var{size}/2\rceil$ limbs.
2278: @end tex
2279: @end iftex
2280: The area at @var{r2p} needs to be @var{size} limbs large.@refill
2281:
2282: @strong{This interface is preliminary. It might change incompatibly in
2283: future revisions.}@refill
2284: @end deftypefun
2285:
2286: @deftypefun mp_size_t mpn_get_str (unsigned char *@var{str}, int @var{base}, mp_limb_t * @var{s1p}, mp_size_t @var{s1size})
2287: Convert @{@var{s1p}, @var{s1size}@} to a raw unsigned char array in base
2288: @var{base}. The string is not in ASCII; to convert it to printable format,
2289: add the ASCII codes for @samp{0} or @samp{A}, depending on the base and
2290: range. There may be leading zeros in the string.@refill
2291:
2292: The area at @var{s1p} is clobbered.@refill
2293:
2294: Return the number of characters in @var{str}.@refill
2295:
2296: The area at @var{str} has to have space for the largest possible number
2297: represented by a @var{s1size} long limb array, plus one extra character.@refill
2298: @end deftypefun
2299:
2300: @deftypefun mp_size_t mpn_set_str (mp_limb_t * @var{r1p}, const char *@var{str}, size_t {strsize}, int @var{base})
2301: Convert the raw unsigned char array at @var{str} of length @var{strsize} to
2302: a limb array @{@var{s1p}, @var{s1size}@}. The base of @var{str} is
2303: @var{base}.@refill
2304:
2305: Return the number of limbs stored in @var{r1p}.@refill
2306: @end deftypefun
2307:
2308: @deftypefun {unsigned long int} mpn_scan0 (const mp_limb_t * @var{s1p}, unsigned long int @var{bit})
2309: Scan @var{s1p} from bit position @var{bit} for the next clear bit.@refill
2310:
2311: It is required that there be a clear bit within the area at @var{s1p} at or
2312: beyond bit position @var{bit}, so that the function has something to return.@refill
2313:
2314: @strong{This interface is preliminary. It might change incompatibly in
2315: future revisions.}@refill
2316: @end deftypefun
2317:
2318: @deftypefun {unsigned long int} mpn_scan1 (const mp_limb_t * @var{s1p}, unsigned long int @var{bit})
2319: Scan @var{s1p} from bit position @var{bit} for the next set bit.@refill
2320:
2321: It is required that there be a set bit within the area at @var{s1p} at or
2322: beyond bit position @var{bit}, so that the function has something to return.@refill
2323:
2324: @strong{This interface is preliminary. It might change incompatibly in
2325: future revisions.}@refill
2326: @end deftypefun
2327:
2328: @deftypefun void mpn_random2 (mp_limb_t * @var{r1p}, mp_size_t @var{r1size})
2329: Generate a random number of length @var{r1size} with long strings of zeros
2330: and ones in the binary representation, and store it at @var{r1p}.@refill
2331:
2332: The generated random numbers are intended for testing the correctness of the
2333: implementation of the @code{mpn} routines.@refill
2334: @end deftypefun
2335:
2336: @deftypefun {unsigned long int} mpn_popcount (const mp_limb_t * @var{s1p}, unsigned long int @var{size})
2337: Count the number of set bits in @{@var{s1p}, @var{size}@}.@refill
2338: @end deftypefun
2339:
2340: @deftypefun {unsigned long int} mpn_hamdist (const mp_limb_t * @var{s1p}, const mp_limb_t * @var{s2p}, unsigned long int @var{size})
2341: Compute the hamming distance between @{@var{s1p}, @var{size}@} and
2342: @{@var{s2p}, @var{size}@}.@refill
2343: @end deftypefun
2344:
2345: @deftypefun int mpn_perfect_square_p (const mp_limb_t * @var{s1p}, mp_size_t @var{size})
2346: Return non-zero iff @{@var{s1p}, @var{size}@} is a perfect square.@refill
2347: @end deftypefun
2348:
2349:
2350: @node BSD Compatible Functions, Custom Allocation, Low-level Functions, Top
2351: @comment node-name, next, previous, up
2352: @chapter Berkeley MP Compatible Functions
2353: @cindex BSD MP compatible functions
2354:
2355: These functions are intended to be fully compatible with the Berkeley MP
2356: library which is available on many BSD derived U*ix systems.@refill
2357:
2358: The original Berkeley MP library has a usage restriction: you cannot use the
2359: same variable as both source and destination in a single function call. The
2360: compatible functions in GNU MP do not share this restriction--inputs and
2361: outputs may overlap.@refill
2362:
2363: It is not recommended that new programs are written using these functions.
2364: Apart from the incomplete set of functions, the interface for initializing
2365: @code{MINT} objects is more error prone, and the @code{pow} function collides
2366: with @code{pow} in @file{libm.a}.@refill
2367:
2368: @cindex @file{mp.h}
2369: Include the header @file{mp.h} to get the definition of the necessary types
2370: and functions. If you are on a BSD derived system, make sure to include GNU
2371: @file{mp.h} if you are going to link the GNU @file{libmp.a} to you program.
2372: This means that you probably need to give the -I<dir> option to the compiler,
2373: where <dir> is the directory where you have GNU @file{mp.h}.@refill
2374:
2375: @deftypefun {MINT *} itom (signed short int @var{initial_value})
2376: Allocate an integer consisting of a @code{MINT} object and dynamic limb space.
2377: Initialize the integer to @var{initial_value}. Return a pointer to the
2378: @code{MINT} object.@refill
2379: @end deftypefun
2380:
2381: @deftypefun {MINT *} xtom (char *@var{initial_value})
2382: Allocate an integer consisting of a @code{MINT} object and dynamic limb space.
2383: Initialize the integer from @var{initial_value}, a hexadecimal, '\0'-terminate
2384: C string. Return a pointer to the @code{MINT} object.@refill
2385: @end deftypefun
2386:
2387: @deftypefun void move (MINT *@var{src}, MINT *@var{dest})
2388: Set @var{dest} to @var{src} by copying. Both variables must be previously
2389: initialized.@refill
2390: @end deftypefun
2391:
2392: @deftypefun void madd (MINT *@var{src_1}, MINT *@var{src_2}, MINT *@var{destination})
2393: Add @var{src_1} and @var{src_2} and put the sum in @var{destination}.@refill
2394: @end deftypefun
2395:
2396: @deftypefun void msub (MINT *@var{src_1}, MINT *@var{src_2}, MINT *@var{destination})
2397: Subtract @var{src_2} from @var{src_1} and put the difference in
2398: @var{destination}.@refill
2399: @end deftypefun
2400:
2401: @deftypefun void mult (MINT *@var{src_1}, MINT *@var{src_2}, MINT *@var{destination})
2402: Multiply @var{src_1} and @var{src_2} and put the product in
2403: @var{destination}.@refill
2404: @end deftypefun
2405:
2406: @deftypefun void mdiv (MINT *@var{dividend}, MINT *@var{divisor}, MINT *@var{quotient}, MINT *@var{remainder})
2407: @deftypefunx void sdiv (MINT *@var{dividend}, signed short int @var{divisor}, MINT *@var{quotient}, signed short int *@var{remainder})
2408: Set @var{quotient} to @var{dividend}/@var{divisor}, and @var{remainder} to
2409: @var{dividend} mod @var{divisor}. The quotient is rounded towards zero; the
2410: remainder has the same sign as the dividend unless it is zero.@refill
2411:
2412: Some implementations of these functions work differently--or not at all--for
2413: negative arguments.@refill
2414: @end deftypefun
2415:
2416: @deftypefun void msqrt (MINT *@var{operand}, MINT *@var{root}, MINT *@var{remainder})
2417: @ifinfo
2418: Set @var{root} to the truncated integer part of the square root of
2419: @var{operand}. Set @var{remainder} to
2420: @var{operand}@minus{}@var{root}*@var{root},@refill
2421: @end ifinfo
2422: @iftex
2423: @tex
2424: Set @var{root} to $\lfloor\sqrt{@var{operand}}\rfloor$, like
2425: @code{mpz_sqrt}. Set @var{remainder} to $(operand - root^2)$,
2426: @end tex
2427: @end iftex
2428: (i.e., zero if @var{operand} is a perfect square).@refill
2429:
2430: If @var{root} and @var{remainder} are the same variable, the results are
2431: undefined.@refill
2432: @end deftypefun
2433:
2434: @deftypefun void pow (MINT *@var{base}, MINT *@var{exp}, MINT *@var{mod}, MINT *@var{dest})
2435: Set @var{dest} to (@var{base} raised to @var{exp}) modulo @var{mod}.@refill
2436: @end deftypefun
2437:
2438: @deftypefun void rpow (MINT *@var{base}, signed short int @var{exp}, MINT *@var{dest})
2439: Set @var{dest} to @var{base} raised to @var{exp}.@refill
2440: @end deftypefun
2441:
2442: @deftypefun void gcd (MINT *@var{operand1}, MINT *@var{operand2}, MINT *@var{res})
2443: Set @var{res} to the greatest common divisor of @var{operand1} and
2444: @var{operand2}.@refill
2445: @end deftypefun
2446:
2447: @deftypefun int mcmp (MINT *@var{operand1}, MINT *@var{operand2})
2448: Compare @var{operand1} and @var{operand2}. Return a positive value if
2449: @var{operand1} > @var{operand2}, zero if @var{operand1} =
2450: @var{operand2}, and a negative value if @var{operand1} < @var{operand2}.@refill
2451: @end deftypefun
2452:
2453: @deftypefun void min (MINT *@var{dest})
2454: Input a decimal string from @code{stdin}, and put the read integer in
2455: @var{dest}. SPC and TAB are allowed in the number string, and are ignored.@refill
2456: @end deftypefun
2457:
2458: @deftypefun void mout (MINT *@var{src})
2459: Output @var{src} to @code{stdout}, as a decimal string. Also output a newline.@refill
2460: @end deftypefun
2461:
2462: @deftypefun {char *} mtox (MINT *@var{operand})
2463: Convert @var{operand} to a hexadecimal string, and return a pointer to the
2464: string. The returned string is allocated using the default memory allocation
2465: function, @code{malloc} by default.@refill
2466: @end deftypefun
2467:
2468: @deftypefun void mfree (MINT *@var{operand})
2469: De-allocate, the space used by @var{operand}. @strong{This function should
2470: only be passed a value returned by @code{itom} or @code{xtom}.}@refill
2471: @end deftypefun
2472:
2473: @node Custom Allocation, Contributors, BSD Compatible Functions, Top
2474: @comment node-name, next, previous, up
2475: @chapter Custom Allocation
2476:
2477: By default, the MP functions use @code{malloc}, @code{realloc}, and
2478: @code{free} for memory allocation. If @code{malloc} or @code{realloc} fails,
2479: the MP library terminates execution after printing a fatal error message to
2480: standard error.@refill
2481:
2482: For some applications, you may wish to allocate memory in other ways, or you
2483: may not want to have a fatal error when there is no more memory available. To
2484: accomplish this, you can specify alternative memory allocation functions.@refill
2485:
2486: @deftypefun void mp_set_memory_functions (@* void *(*@var{alloc_func_ptr}) (size_t), @* void *(*@var{realloc_func_ptr}) (void *, size_t, size_t), @* void (*@var{free_func_ptr}) (void *, size_t))
2487: Replace the current allocation functions from the arguments. If an argument
2488: is NULL, the corresponding default function is retained.@refill
2489:
2490: @strong{Make sure to call this function in such a way that there are no active
2491: MP objects that were allocated using the previously active allocation
2492: function! Usually, that means that you have to call this function before any
2493: other MP function.}@refill
2494: @end deftypefun
2495:
2496: The functions you supply should fit the following declarations:@refill
2497:
2498: @deftypefun {void *} allocate_function (size_t @var{alloc_size})
2499: This function should return a pointer to newly allocated space with at least
2500: @var{alloc_size} storage units.@refill
2501: @end deftypefun
2502:
2503: @deftypefun {void *} reallocate_function (void *@var{ptr}, size_t @var{old_size}, size_t @var{new_size})
2504: This function should return a pointer to newly allocated space of at least
2505: @var{new_size} storage units, after copying at least the first @var{old_size}
2506: storage units from @var{ptr}. It should also de-allocate the space at
2507: @var{ptr}.@refill
2508:
2509: You can assume that the space at @var{ptr} was formerly returned from
2510: @code{allocate_function} or @code{reallocate_function}, for a request for
2511: @var{old_size} storage units.@refill
2512: @end deftypefun
2513:
2514: @deftypefun void deallocate_function (void *@var{ptr}, size_t @var{size})
2515: De-allocate the space pointed to by @var{ptr}.@refill
2516:
2517: You can assume that the space at @var{ptr} was formerly returned from
2518: @code{allocate_function} or @code{reallocate_function}, for a request for
2519: @var{size} storage units.@refill
2520: @end deftypefun
2521:
2522: (A @dfn{storage unit} is the unit in which the @code{sizeof} operator returns
2523: the size of an object, normally an 8 bit byte.)@refill
2524:
2525:
2526: @node Contributors, References, Custom Allocation, Top
2527: @comment node-name, next, previous, up
2528: @unnumbered Contributors
2529:
2530: I would like to thank Gunnar Sjoedin and Hans Riesel for their help with
2531: mathematical problems, Richard Stallman for his help with design issues and
2532: for revising the first version of this manual, Brian Beuning and Doug Lea for
2533: their testing of early versions of the library.@refill
2534:
2535: John Amanatides of York University in Canada contributed the function
2536: @code{mpz_probab_prime_p}.@refill
2537:
2538: Paul Zimmermann of Inria sparked the development of GMP 2, with his
2539: comparisons between bignum packages.@refill
2540:
2541: Ken Weber (Kent State University, Universidade Federal do Rio Grande do Sul)
2542: contributed @code{mpz_gcd}, @code{mpz_divexact}, @code{mpn_gcd}, and
2543: @code{mpn_bdivmod}, partially supported by CNPq (Brazil) grant 301314194-2.@refill
2544:
2545: Per Bothner of Cygnus Support helped to set up MP to use Cygnus' configure.
2546: He has also made valuable suggestions and tested numerous intermediary
2547: releases.@refill
2548:
2549: Joachim Hollman was involved in the design of the @code{mpf} interface, and in
2550: the @code{mpz} design revisions for version 2.@refill
2551:
2552: Bennet Yee contributed the functions @code{mpz_jacobi} and
2553: @code{mpz_legendre}.@refill
2554:
2555: Andreas Schwab contributed the files @file{mpn/m68k/lshift.S} and
2556: @file{mpn/m68k/rshift.S}.@refill
2557:
2558: The development of floating point functions of GNU MP 2, were supported in
2559: part by the ESPRIT-BRA (Basic Research Activities) 6846 project POSSO
2560: (POlynomial System SOlving).@refill
2561:
2562: GNU MP 2 was finished and released by TMG Datakonsult, Sodermannagatan 5, 116
2563: 23 STOCKHOLM, SWEDEN, in cooperation with the IDA Center for Computing
2564: Sciences, USA.@refill
2565:
2566:
2567: @node References, , Contributors, Top
2568: @comment node-name, next, previous, up
2569: @unnumbered References
2570:
2571: @itemize @bullet
2572:
2573: @item
2574: Donald E. Knuth, "The Art of Computer Programming", vol 2,
2575: "Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981.@refill
2576:
2577: @item
2578: John D. Lipson, "Elements of Algebra and Algebraic Computing",
2579: The Benjamin Cummings Publishing Company Inc, 1981.@refill
2580:
2581: @item
2582: Richard M. Stallman, "Using and Porting GCC", Free Software Foundation,
2583: 1995.@refill
2584:
2585: @item
2586: Peter L. Montgomery, "Modular Multiplication Without Trial Division", in
2587: Mathematics of Computation, volume 44, number 170, April 1985.@refill
2588:
2589: @item
2590: Torbjorn Granlund and Peter L. Montgomery, "Division by Invariant
2591: Integers using Multiplication", in Proceedings of the SIGPLAN
2592: PLDI'94 Conference, June 1994.@refill
2593:
2594: @item
2595: Tudor Jebelean,
2596: "An algorithm for exact division",
2597: Journal of Symbolic Computation,
2598: v. 15, 1993, pp. 169-180.@refill
2599:
2600: @item
2601: Kenneth Weber, "The accelerated integer GCD algorithm",
2602: ACM Transactions on Mathematical Software,
2603: v. 21 (March), 1995, pp. 111-122.@refill
2604: @end itemize
2605:
2606: @node Concept Index, , , Top
2607: @comment node-name, next, previous, up
2608: @unnumbered Concept Index
2609: @printindex cp
2610:
2611: @node Function Index, , , Top
2612: @comment node-name, next, previous, up
2613: @unnumbered Function and Type Index
2614: @printindex fn
2615:
2616:
2617: @contents
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to gmp.info CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM / src / kan96xx / gmp-2.0.2