1 This is Info file gmp.info, produced by Makeinfo-1.64 from the input
5 * gmp: (gmp.info). GNU Multiple Precision Arithmetic Library.
8 This file documents GNU MP, a library for arbitrary-precision
11 Copyright (C) 1991, 1993, 1994, 1995, 1996 Free Software Foundation,
14 Permission is granted to make and distribute verbatim copies of this
15 manual provided the copyright notice and this permission notice are
16 preserved on all copies.
18 Permission is granted to copy and distribute modified versions of
19 this manual under the conditions for verbatim copying, provided that
20 the entire resulting derived work is distributed under the terms of a
21 permission notice identical to this one.
23 Permission is granted to copy and distribute translations of this
24 manual into another language, under the above conditions for modified
25 versions, except that this permission notice may be stated in a
26 translation approved by the Foundation.
29 File: gmp.info, Node: Floating-point Functions, Next: Low-level Functions, Prev: Rational Number Functions, Up: Top
31 Floating-point Functions
32 ************************
34 This is a description of the *preliminary* interface for
35 floating-point arithmetic in GNU MP 2.
37 The floating-point functions expect arguments of type `mpf_t'.
39 The MP floating-point functions have an interface that is similar to
40 the MP integer functions. The function prefix for floating-point
43 There is one significant characteristic of floating-point numbers
44 that has motivated a difference between this function class and other
45 MP function classes: the inherent inexactness of floating point
46 arithmetic. The user has to specify the precision of each variable. A
47 computation that assigns a variable will take place with the precision
48 of the assigned variable; the precision of variables used as input is
51 The precision of a calculation is defined as follows: Compute the
52 requested operation exactly (with "infinite precision"), and truncate
53 the result to the destination variable precision. Even if the user has
54 asked for a very high precision, MP will not calculate with superfluous
55 digits. For example, if two low-precision numbers of nearly equal
56 magnitude are added, the precision of the result will be limited to
57 what is required to represent the result accurately.
59 The MP floating-point functions are *not* intended as a smooth
60 extension to the IEEE P754 arithmetic. Specifically, the results
61 obtained on one computer often differs from the results obtained on a
62 computer with a different word size.
66 * Initializing Floats::
68 * Simultaneous Float Init & Assign::
73 * Miscellaneous Float Functions::
76 File: gmp.info, Node: Initializing Floats, Next: Assigning Floats, Up: Floating-point Functions
78 Initialization and Assignment Functions
79 =======================================
81 - Function: void mpf_set_default_prec (unsigned long int PREC)
82 Set the default precision to be *at least* PREC bits. All
83 subsequent calls to `mpf_init' will use this precision, but
84 previously initialized variables are unaffected.
86 An `mpf_t' object must be initialized before storing the first value
87 in it. The functions `mpf_init' and `mpf_init2' are used for that
90 - Function: void mpf_init (mpf_t X)
91 Initialize X to 0. Normally, a variable should be initialized
92 once only or at least be cleared, using `mpf_clear', between
93 initializations. The precision of X is undefined unless a default
94 precision has already been established by a call to
95 `mpf_set_default_prec'.
97 - Function: void mpf_init2 (mpf_t X, unsigned long int PREC)
98 Initialize X to 0 and set its precision to be *at least* PREC
99 bits. Normally, a variable should be initialized once only or at
100 least be cleared, using `mpf_clear', between initializations.
102 - Function: void mpf_clear (mpf_t X)
103 Free the space occupied by X. Make sure to call this function for
104 all `mpf_t' variables when you are done with them.
106 Here is an example on how to initialize floating-point variables:
109 mpf_init (x); /* use default precision */
110 mpf_init2 (y, 256); /* precision *at least* 256 bits */
112 /* Unless the program is about to exit, do ... */
117 The following three functions are useful for changing the precision
118 during a calculation. A typical use would be for adjusting the
119 precision gradually in iterative algorithms like Newton-Raphson, making
120 the computation precision closely match the actual accurate part of the
123 - Function: void mpf_set_prec (mpf_t ROP, unsigned long int PREC)
124 Set the precision of ROP to be *at least* PREC bits. Since
125 changing the precision involves calls to `realloc', this routine
126 should not be called in a tight loop.
128 - Function: unsigned long int mpf_get_prec (mpf_t OP)
129 Return the precision actually used for assignments of OP.
131 - Function: void mpf_set_prec_raw (mpf_t ROP, unsigned long int PREC)
132 Set the precision of ROP to be *at least* PREC bits. This is a
133 low-level function that does not change the allocation. The PREC
134 argument must not be larger that the precision previously returned
135 by `mpf_get_prec'. It is crucial that the precision of ROP is
136 ultimately reset to exactly the value returned by `mpf_get_prec'.
139 File: gmp.info, Node: Assigning Floats, Next: Simultaneous Float Init & Assign, Prev: Initializing Floats, Up: Floating-point Functions
144 These functions assign new values to already initialized floats
145 (*note Initializing Floats::.).
147 - Function: void mpf_set (mpf_t ROP, mpf_t OP)
148 - Function: void mpf_set_ui (mpf_t ROP, unsigned long int OP)
149 - Function: void mpf_set_si (mpf_t ROP, signed long int OP)
150 - Function: void mpf_set_d (mpf_t ROP, double OP)
151 - Function: void mpf_set_z (mpf_t ROP, mpz_t OP)
152 - Function: void mpf_set_q (mpf_t ROP, mpq_t OP)
153 Set the value of ROP from OP.
155 - Function: int mpf_set_str (mpf_t ROP, char *STR, int BASE)
156 Set the value of ROP from the string in STR. The string is of the
157 form `M@N' or, if the base is 10 or less, alternatively `MeN'.
158 `M' is the mantissa and `N' is the exponent. The mantissa is
159 always in the specified base. The exponent is either in the
160 specified base or, if BASE is negative, in decimal.
162 The argument BASE may be in the ranges 2 to 36, or -36 to -2.
163 Negative values are used to specify that the exponent is in
166 Unlike the corresponding `mpz' function, the base will not be
167 determined from the leading characters of the string if BASE is 0.
168 This is so that numbers like `0.23' are not interpreted as octal.
170 White space is allowed in the string, and is simply ignored.
172 This function returns 0 if the entire string up to the '\0' is a
173 valid number in base BASE. Otherwise it returns -1.
176 File: gmp.info, Node: Simultaneous Float Init & Assign, Next: Converting Floats, Prev: Assigning Floats, Up: Floating-point Functions
178 Combined Initialization and Assignment Functions
179 ------------------------------------------------
181 For convenience, MP provides a parallel series of initialize-and-set
182 functions which initialize the output and then store the value there.
183 These functions' names have the form `mpf_init_set...'
185 Once the float has been initialized by any of the `mpf_init_set...'
186 functions, it can be used as the source or destination operand for the
187 ordinary float functions. Don't use an initialize-and-set function on
188 a variable already initialized!
190 - Function: void mpf_init_set (mpf_t ROP, mpf_t OP)
191 - Function: void mpf_init_set_ui (mpf_t ROP, unsigned long int OP)
192 - Function: void mpf_init_set_si (mpf_t ROP, signed long int OP)
193 - Function: void mpf_init_set_d (mpf_t ROP, double OP)
194 Initialize ROP and set its value from OP.
196 The precision of ROP will be taken from the active default
197 precision, as set by `mpf_set_default_prec'.
199 - Function: int mpf_init_set_str (mpf_t ROP, char *STR, int BASE)
200 Initialize ROP and set its value from the string in STR. See
201 `mpf_set_str' above for details on the assignment operation.
203 Note that ROP is initialized even if an error occurs. (I.e., you
204 have to call `mpf_clear' for it.)
206 The precision of ROP will be taken from the active default
207 precision, as set by `mpf_set_default_prec'.
210 File: gmp.info, Node: Converting Floats, Next: Float Arithmetic, Prev: Simultaneous Float Init & Assign, Up: Floating-point Functions
215 - Function: double mpf_get_d (mpf_t OP)
216 Convert OP to a double.
218 - Function: char * mpf_get_str (char *STR, mp_exp_t *EXPPTR, int BASE,
219 size_t N_DIGITS, mpf_t OP)
220 Convert OP to a string of digits in base BASE. The base may vary
221 from 2 to 36. Generate at most N_DIGITS significant digits, or if
222 N_DIGITS is 0, the maximum number of digits accurately
225 If STR is NULL, space for the mantissa is allocated using the
226 default allocation function, and a pointer to the string is
229 If STR is not NULL, it should point to a block of storage enough
230 large for the mantissa, i.e., N_DIGITS + 2. The two extra bytes
231 are for a possible minus sign, and for the terminating null
234 The exponent is written through the pointer EXPPTR.
236 If N_DIGITS is 0, the maximum number of digits meaningfully
237 achievable from the precision of OP will be generated. Note that
238 the space requirements for STR in this case will be impossible for
239 the user to predetermine. Therefore, you need to pass NULL for
240 the string argument whenever N_DIGITS is 0.
242 The generated string is a fraction, with an implicit radix point
243 immediately to the left of the first digit. For example, the
244 number 3.1416 would be returned as "31416" in the string and 1
248 File: gmp.info, Node: Float Arithmetic, Next: Float Comparison, Prev: Converting Floats, Up: Floating-point Functions
253 - Function: void mpf_add (mpf_t ROP, mpf_t OP1, mpf_t OP2)
254 - Function: void mpf_add_ui (mpf_t ROP, mpf_t OP1, unsigned long int
256 Set ROP to OP1 + OP2.
258 - Function: void mpf_sub (mpf_t ROP, mpf_t OP1, mpf_t OP2)
259 - Function: void mpf_ui_sub (mpf_t ROP, unsigned long int OP1, mpf_t
261 - Function: void mpf_sub_ui (mpf_t ROP, mpf_t OP1, unsigned long int
263 Set ROP to OP1 - OP2.
265 - Function: void mpf_mul (mpf_t ROP, mpf_t OP1, mpf_t OP2)
266 - Function: void mpf_mul_ui (mpf_t ROP, mpf_t OP1, unsigned long int
268 Set ROP to OP1 times OP2.
270 Division is undefined if the divisor is zero, and passing a zero
271 divisor to the divide functions will make these functions intentionally
272 divide by zero. This gives the user the possibility to handle
273 arithmetic exceptions in these functions in the same manner as other
274 arithmetic exceptions.
276 - Function: void mpf_div (mpf_t ROP, mpf_t OP1, mpf_t OP2)
277 - Function: void mpf_ui_div (mpf_t ROP, unsigned long int OP1, mpf_t
279 - Function: void mpf_div_ui (mpf_t ROP, mpf_t OP1, unsigned long int
283 - Function: void mpf_sqrt (mpf_t ROP, mpf_t OP)
284 - Function: void mpf_sqrt_ui (mpf_t ROP, unsigned long int OP)
285 Set ROP to the square root of OP.
287 - Function: void mpf_neg (mpf_t ROP, mpf_t OP)
290 - Function: void mpf_abs (mpf_t ROP, mpf_t OP)
291 Set ROP to the absolute value of OP.
293 - Function: void mpf_mul_2exp (mpf_t ROP, mpf_t OP1, unsigned long int
295 Set ROP to OP1 times 2 raised to OP2.
297 - Function: void mpf_div_2exp (mpf_t ROP, mpf_t OP1, unsigned long int
299 Set ROP to OP1 divided by 2 raised to OP2.
302 File: gmp.info, Node: Float Comparison, Next: I/O of Floats, Prev: Float Arithmetic, Up: Floating-point Functions
307 - Function: int mpf_cmp (mpf_t OP1, mpf_t OP2)
308 - Function: int mpf_cmp_ui (mpf_t OP1, unsigned long int OP2)
309 - Function: int mpf_cmp_si (mpf_t OP1, signed long int OP2)
310 Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
311 if OP1 = OP2, and a negative value if OP1 < OP2.
313 - Function: int mpf_eq (mpf_t OP1, mpf_t OP2, unsigned long int op3)
314 Return non-zero if the first OP3 bits of OP1 and OP2 are equal,
315 zero otherwise. I.e., test of OP1 and OP2 are approximately equal.
317 - Function: void mpf_reldiff (mpf_t ROP, mpf_t OP1, mpf_t OP2)
318 Compute the relative difference between OP1 and OP2 and store the
321 - Macro: int mpf_sgn (mpf_t OP)
322 Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.
324 This function is actually implemented as a macro. It evaluates its
325 arguments multiple times.
328 File: gmp.info, Node: I/O of Floats, Next: Miscellaneous Float Functions, Prev: Float Comparison, Up: Floating-point Functions
330 Input and Output Functions
331 ==========================
333 Functions that perform input from a stdio stream, and functions that
334 output to a stdio stream. Passing a NULL pointer for a STREAM argument
335 to any of these functions will make them read from `stdin' and write to
336 `stdout', respectively.
338 When using any of these functions, it is a good idea to include
339 `stdio.h' before `gmp.h', since that will allow `gmp.h' to define
340 prototypes for these functions.
342 - Function: size_t mpf_out_str (FILE *STREAM, int BASE, size_t
344 Output OP on stdio stream STREAM, as a string of digits in base
345 BASE. The base may vary from 2 to 36. Print at most N_DIGITS
346 significant digits, or if N_DIGITS is 0, the maximum number of
347 digits accurately representable by OP.
349 In addition to the significant digits, a leading `0.' and a
350 trailing exponent, in the form `eNNN', are printed. If BASE is
351 greater than 10, `@' will be used instead of `e' as exponent
354 Return the number of bytes written, or if an error occurred,
357 - Function: size_t mpf_inp_str (mpf_t ROP, FILE *STREAM, int BASE)
358 Input a string in base BASE from stdio stream STREAM, and put the
359 read float in ROP. The string is of the form `M@N' or, if the
360 base is 10 or less, alternatively `MeN'. `M' is the mantissa and
361 `N' is the exponent. The mantissa is always in the specified
362 base. The exponent is either in the specified base or, if BASE is
363 negative, in decimal.
365 The argument BASE may be in the ranges 2 to 36, or -36 to -2.
366 Negative values are used to specify that the exponent is in
369 Unlike the corresponding `mpz' function, the base will not be
370 determined from the leading characters of the string if BASE is 0.
371 This is so that numbers like `0.23' are not interpreted as octal.
373 Return the number of bytes read, or if an error occurred, return 0.
376 File: gmp.info, Node: Miscellaneous Float Functions, Prev: I/O of Floats, Up: Floating-point Functions
378 Miscellaneous Functions
379 =======================
381 - Function: void mpf_random2 (mpf_t ROP, mp_size_t MAX_SIZE, mp_exp_t
383 Generate a random float of at most MAX_SIZE limbs, with long
384 strings of zeros and ones in the binary representation. The
385 exponent of the number is in the interval -EXP to EXP. This
386 function is useful for testing functions and algorithms, since
387 this kind of random numbers have proven to be more likely to
388 trigger corner-case bugs. Negative random numbers are generated
389 when MAX_SIZE is negative.
392 File: gmp.info, Node: Low-level Functions, Next: BSD Compatible Functions, Prev: Floating-point Functions, Up: Top
397 This chapter describes low-level MP functions, used to implement the
398 high-level MP functions, but also intended for time-critical user code.
400 These functions start with the prefix `mpn_'.
402 The `mpn' functions are designed to be as fast as possible, *not* to
403 provide a coherent calling interface. The different functions have
404 somewhat similar interfaces, but there are variations that make them
405 hard to use. These functions do as little as possible apart from the
406 real multiple precision computation, so that no time is spent on things
407 that not all callers need.
409 A source operand is specified by a pointer to the least significant
410 limb and a limb count. A destination operand is specified by just a
411 pointer. It is the responsibility of the caller to ensure that the
412 destination has enough space for storing the result.
414 With this way of specifying operands, it is possible to perform
415 computations on subranges of an argument, and store the result into a
416 subrange of a destination.
418 A common requirement for all functions is that each source area
419 needs at least one limb. No size argument may be zero.
421 The `mpn' functions is the base for the implementation of the `mpz_',
422 `mpf_', and `mpq_' functions.
424 This example adds the number beginning at SRC1_PTR and the number
425 beginning at SRC2_PTR and writes the sum at DEST_PTR. All areas have
428 cy = mpn_add_n (dest_ptr, src1_ptr, src2_ptr, size)
430 In the notation used here, a source operand is identified by the
431 pointer to the least significant limb, and the limb count in braces.
432 For example, {s1_ptr, s1_size}.
434 - Function: mp_limb_t mpn_add_n (mp_limb_t * DEST_PTR, const mp_limb_t
435 * SRC1_PTR, const mp_limb_t * SRC2_PTR, mp_size_t SIZE)
436 Add {SRC1_PTR, SIZE} and {SRC2_PTR, SIZE}, and write the SIZE
437 least significant limbs of the result to DEST_PTR. Return carry,
440 This is the lowest-level function for addition. It is the
441 preferred function for addition, since it is written in assembly
442 for most targets. For addition of a variable to itself (i.e.,
443 SRC1_PTR equals SRC2_PTR, use `mpn_lshift' with a count of 1 for
446 - Function: mp_limb_t mpn_add_1 (mp_limb_t * DEST_PTR, const mp_limb_t
447 * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB)
448 Add {SRC1_PTR, SIZE} and SRC2_LIMB, and write the SIZE least
449 significant limbs of the result to DEST_PTR. Return carry, either
452 - Function: mp_limb_t mpn_add (mp_limb_t * DEST_PTR, const mp_limb_t *
453 SRC1_PTR, mp_size_t SRC1_SIZE, const mp_limb_t * SRC2_PTR,
455 Add {SRC1_PTR, SRC1_SIZE} and {SRC2_PTR, SRC2_SIZE}, and write the
456 SRC1_SIZE least significant limbs of the result to DEST_PTR.
457 Return carry, either 0 or 1.
459 This function requires that SRC1_SIZE is greater than or equal to
462 - Function: mp_limb_t mpn_sub_n (mp_limb_t * DEST_PTR, const mp_limb_t
463 * SRC1_PTR, const mp_limb_t * SRC2_PTR, mp_size_t SIZE)
464 Subtract {SRC2_PTR, SRC2_SIZE} from {SRC1_PTR, SIZE}, and write
465 the SIZE least significant limbs of the result to DEST_PTR.
466 Return borrow, either 0 or 1.
468 This is the lowest-level function for subtraction. It is the
469 preferred function for subtraction, since it is written in
470 assembly for most targets.
472 - Function: mp_limb_t mpn_sub_1 (mp_limb_t * DEST_PTR, const mp_limb_t
473 * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB)
474 Subtract SRC2_LIMB from {SRC1_PTR, SIZE}, and write the SIZE least
475 significant limbs of the result to DEST_PTR. Return borrow,
478 - Function: mp_limb_t mpn_sub (mp_limb_t * DEST_PTR, const mp_limb_t *
479 SRC1_PTR, mp_size_t SRC1_SIZE, const mp_limb_t * SRC2_PTR,
481 Subtract {SRC2_PTR, SRC2_SIZE} from {SRC1_PTR, SRC1_SIZE}, and
482 write the SRC1_SIZE least significant limbs of the result to
483 DEST_PTR. Return borrow, either 0 or 1.
485 This function requires that SRC1_SIZE is greater than or equal to
488 - Function: void mpn_mul_n (mp_limb_t * DEST_PTR, const mp_limb_t *
489 SRC1_PTR, const mp_limb_t * SRC2_PTR, mp_size_t SIZE)
490 Multiply {SRC1_PTR, SIZE} and {SRC2_PTR, SIZE}, and write the
491 *entire* result to DEST_PTR.
493 The destination has to have space for 2SIZE limbs, even if the
494 significant result might be one limb smaller.
496 - Function: mp_limb_t mpn_mul_1 (mp_limb_t * DEST_PTR, const mp_limb_t
497 * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB)
498 Multiply {SRC1_PTR, SIZE} and SRC2_LIMB, and write the SIZE least
499 significant limbs of the product to DEST_PTR. Return the most
500 significant limb of the product.
502 This is a low-level function that is a building block for general
503 multiplication as well as other operations in MP. It is written
504 in assembly for most targets.
506 Don't call this function if SRC2_LIMB is a power of 2; use
507 `mpn_lshift' with a count equal to the logarithm of SRC2_LIMB
508 instead, for optimal speed.
510 - Function: mp_limb_t mpn_addmul_1 (mp_limb_t * DEST_PTR, const
511 mp_limb_t * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB)
512 Multiply {SRC1_PTR, SIZE} and SRC2_LIMB, and add the SIZE least
513 significant limbs of the product to {DEST_PTR, SIZE} and write the
514 result to DEST_PTR DEST_PTR. Return the most significant limb of
515 the product, plus carry-out from the addition.
517 This is a low-level function that is a building block for general
518 multiplication as well as other operations in MP. It is written
519 in assembly for most targets.
521 - Function: mp_limb_t mpn_submul_1 (mp_limb_t * DEST_PTR, const
522 mp_limb_t * SRC1_PTR, mp_size_t SIZE, mp_limb_t SRC2_LIMB)
523 Multiply {SRC1_PTR, SIZE} and SRC2_LIMB, and subtract the SIZE
524 least significant limbs of the product from {DEST_PTR, SIZE} and
525 write the result to DEST_PTR. Return the most significant limb of
526 the product, minus borrow-out from the subtraction.
528 This is a low-level function that is a building block for general
529 multiplication and division as well as other operations in MP. It
530 is written in assembly for most targets.
532 - Function: mp_limb_t mpn_mul (mp_limb_t * DEST_PTR, const mp_limb_t *
533 SRC1_PTR, mp_size_t SRC1_SIZE, const mp_limb_t * SRC2_PTR,
535 Multiply {SRC1_PTR, SRC1_SIZE} and {SRC2_PTR, SRC2_SIZE}, and
536 write the result to DEST_PTR. Return the most significant limb of
539 The destination has to have space for SRC1_SIZE + SRC1_SIZE limbs,
540 even if the result might be one limb smaller.
542 This function requires that SRC1_SIZE is greater than or equal to
543 SRC2_SIZE. The destination must be distinct from either input
546 - Function: mp_size_t mpn_divrem (mp_limb_t * R1P, mp_size_t XSIZE,
547 mp_limb_t * RS2P, mp_size_t RS2SIZE, const mp_limb_t * S3P,
549 Divide {RS2P, RS2SIZE} by {S3P, S3SIZE}, and write the quotient at
550 R1P, with the exception of the most significant limb, which is
551 returned. The remainder replaces the dividend at RS2P.
553 In addition to an integer quotient, XSIZE fraction limbs are
554 developed, and stored after the integral limbs. For most usages,
557 It is required that RS2SIZE is greater than or equal to S3SIZE.
558 It is required that the most significant bit of the divisor is set.
560 If the quotient is not needed, pass RS2P + S3SIZE as R1P. Aside
561 from that special case, no overlap between arguments is permitted.
563 Return the most significant limb of the quotient, either 0 or 1.
565 The area at R1P needs to be RS2SIZE - S3SIZE + XSIZE limbs large.
567 - Function: mp_limb_t mpn_divrem_1 (mp_limb_t * R1P, mp_size_t XSIZE,
568 mp_limb_t * S2P, mp_size_t S2SIZE, mp_limb_t S3LIMB)
569 Divide {S2P, S2SIZE} by S3LIMB, and write the quotient at R1P.
570 Return the remainder.
572 In addition to an integer quotient, XSIZE fraction limbs are
573 developed, and stored after the integral limbs. For most usages,
576 The areas at R1P and S2P have to be identical or completely
577 separate, not partially overlapping.
579 - Function: mp_size_t mpn_divmod (mp_limb_t * R1P, mp_limb_t * RS2P,
580 mp_size_t RS2SIZE, const mp_limb_t * S3P, mp_size_t S3SIZE)
581 *This interface is obsolete. It will disappear from future
582 releases. Use `mpn_divrem' in its stead.*
584 - Function: mp_limb_t mpn_divmod_1 (mp_limb_t * R1P, mp_limb_t * S2P,
585 mp_size_t S2SIZE, mp_limb_t S3LIMB)
586 *This interface is obsolete. It will disappear from future
587 releases. Use `mpn_divrem_1' in its stead.*
589 - Function: mp_limb_t mpn_mod_1 (mp_limb_t * S1P, mp_size_t S1SIZE,
591 Divide {S1P, S1SIZE} by S2LIMB, and return the remainder.
593 - Function: mp_limb_t mpn_preinv_mod_1 (mp_limb_t * S1P, mp_size_t
594 S1SIZE, mp_limb_t S2LIMB, mp_limb_t S3LIMB)
595 *This interface is obsolete. It will disappear from future
596 releases. Use `mpn_mod_1' in its stead.*
598 - Function: mp_limb_t mpn_bdivmod (mp_limb_t * DEST_PTR, mp_limb_t *
599 S1P, mp_size_t S1SIZE, const mp_limb_t * S2P, mp_size_t
600 S2SIZE, unsigned long int D)
601 The function puts the low [D/BITS_PER_MP_LIMB] limbs of Q = {S1P,
602 S1SIZE}/{S2P, S2SIZE} mod 2^D at DEST_PTR, and returns the high D
603 mod BITS_PER_MP_LIMB bits of Q.
605 {S1P, S1SIZE} - Q * {S2P, S2SIZE} mod 2^(S1SIZE*BITS_PER_MP_LIMB)
606 is placed at S1P. Since the low [D/BITS_PER_MP_LIMB] limbs of
607 this difference are zero, it is possible to overwrite the low
608 limbs at S1P with this difference, provided DEST_PTR <= S1P.
610 This function requires that S1SIZE * BITS_PER_MP_LIMB >= D, and
611 that {S2P, S2SIZE} is odd.
613 *This interface is preliminary. It might change incompatibly in
616 - Function: mp_limb_t mpn_lshift (mp_limb_t * DEST_PTR, const
617 mp_limb_t * SRC_PTR, mp_size_t SRC_SIZE, unsigned long int
619 Shift {SRC_PTR, SRC_SIZE} COUNT bits to the left, and write the
620 SRC_SIZE least significant limbs of the result to DEST_PTR. COUNT
621 might be in the range 1 to n - 1, on an n-bit machine. The bits
622 shifted out to the left are returned.
624 Overlapping of the destination space and the source space is
625 allowed in this function, provided DEST_PTR >= SRC_PTR.
627 This function is written in assembly for most targets.
629 - Function: mp_limp_t mpn_rshift (mp_limb_t * DEST_PTR, const
630 mp_limb_t * SRC_PTR, mp_size_t SRC_SIZE, unsigned long int
632 Shift {SRC_PTR, SRC_SIZE} COUNT bits to the right, and write the
633 SRC_SIZE most significant limbs of the result to DEST_PTR. COUNT
634 might be in the range 1 to n - 1, on an n-bit machine. The bits
635 shifted out to the right are returned.
637 Overlapping of the destination space and the source space is
638 allowed in this function, provided DEST_PTR <= SRC_PTR.
640 This function is written in assembly for most targets.
642 - Function: int mpn_cmp (const mp_limb_t * SRC1_PTR, const mp_limb_t *
643 SRC2_PTR, mp_size_t SIZE)
644 Compare {SRC1_PTR, SIZE} and {SRC2_PTR, SIZE} and return a
645 positive value if src1 > src2, 0 of they are equal, and a negative
646 value if src1 < src2.
648 - Function: mp_size_t mpn_gcd (mp_limb_t * DEST_PTR, mp_limb_t *
649 SRC1_PTR, mp_size_t SRC1_SIZE, mp_limb_t * SRC2_PTR,
651 Puts at DEST_PTR the greatest common divisor of {SRC1_PTR,
652 SRC1_SIZE} and {SRC2_PTR, SRC2_SIZE}; both source operands are
653 destroyed by the operation. The size in limbs of the greatest
654 common divisor is returned.
656 {SRC1_PTR, SRC1_SIZE} must be odd, and {SRC2_PTR, SRC2_SIZE} must
657 have at least as many bits as {SRC1_PTR, SRC1_SIZE}.
659 *This interface is preliminary. It might change incompatibly in
662 - Function: mp_limb_t mpn_gcd_1 (const mp_limb_t * SRC1_PTR, mp_size_t
663 SRC1_SIZE, mp_limb_t SRC2_LIMB)
664 Return the greatest common divisor of {SRC1_PTR, SRC1_SIZE} and
665 SRC2_LIMB, where SRC2_LIMB (as well as SRC1_SIZE) must be
668 - Function: mp_size_t mpn_gcdext (mp_limb_t * R1P, mp_limb_t * R2P,
669 mp_limb_t * S1P, mp_size_t S1SIZE, mp_limb_t * S2P, mp_size_t
671 Puts at R1P the greatest common divisor of {S1P, S1SIZE} and {S2P,
672 S2SIZE}. The first cofactor is written at R2P. Both source
673 operands are destroyed by the operation. The size in limbs of the
674 greatest common divisor is returned.
676 *This interface is preliminary. It might change incompatibly in
679 - Function: mp_size_t mpn_sqrtrem (mp_limb_t * R1P, mp_limb_t * R2P,
680 const mp_limb_t * SP, mp_size_t SIZE)
681 Compute the square root of {SP, SIZE} and put the result at R1P.
682 Write the remainder at R2P, unless R2P is NULL.
684 Return the size of the remainder, whether R2P was NULL or non-NULL.
685 Iff the operand was a perfect square, the return value will be 0.
687 The areas at R1P and SP have to be distinct. The areas at R2P and
688 SP have to be identical or completely separate, not partially
691 The area at R1P needs to have space for ceil(SIZE/2) limbs. The
692 area at R2P needs to be SIZE limbs large.
694 *This interface is preliminary. It might change incompatibly in
697 - Function: mp_size_t mpn_get_str (unsigned char *STR, int BASE,
698 mp_limb_t * S1P, mp_size_t S1SIZE)
699 Convert {S1P, S1SIZE} to a raw unsigned char array in base BASE.
700 The string is not in ASCII; to convert it to printable format, add
701 the ASCII codes for `0' or `A', depending on the base and range.
702 There may be leading zeros in the string.
704 The area at S1P is clobbered.
706 Return the number of characters in STR.
708 The area at STR has to have space for the largest possible number
709 represented by a S1SIZE long limb array, plus one extra character.
711 - Function: mp_size_t mpn_set_str (mp_limb_t * R1P, const char *STR,
712 size_t strsize, int BASE)
713 Convert the raw unsigned char array at STR of length STRSIZE to a
714 limb array {S1P, S1SIZE}. The base of STR is BASE.
716 Return the number of limbs stored in R1P.
718 - Function: unsigned long int mpn_scan0 (const mp_limb_t * S1P,
719 unsigned long int BIT)
720 Scan S1P from bit position BIT for the next clear bit.
722 It is required that there be a clear bit within the area at S1P at
723 or beyond bit position BIT, so that the function has something to
726 *This interface is preliminary. It might change incompatibly in
729 - Function: unsigned long int mpn_scan1 (const mp_limb_t * S1P,
730 unsigned long int BIT)
731 Scan S1P from bit position BIT for the next set bit.
733 It is required that there be a set bit within the area at S1P at or
734 beyond bit position BIT, so that the function has something to
737 *This interface is preliminary. It might change incompatibly in
740 - Function: void mpn_random2 (mp_limb_t * R1P, mp_size_t R1SIZE)
741 Generate a random number of length R1SIZE with long strings of
742 zeros and ones in the binary representation, and store it at R1P.
744 The generated random numbers are intended for testing the
745 correctness of the implementation of the `mpn' routines.
747 - Function: unsigned long int mpn_popcount (const mp_limb_t * S1P,
748 unsigned long int SIZE)
749 Count the number of set bits in {S1P, SIZE}.
751 - Function: unsigned long int mpn_hamdist (const mp_limb_t * S1P,
752 const mp_limb_t * S2P, unsigned long int SIZE)
753 Compute the hamming distance between {S1P, SIZE} and {S2P, SIZE}.
755 - Function: int mpn_perfect_square_p (const mp_limb_t * S1P, mp_size_t
757 Return non-zero iff {S1P, SIZE} is a perfect square.
760 File: gmp.info, Node: BSD Compatible Functions, Next: Custom Allocation, Prev: Low-level Functions, Up: Top
762 Berkeley MP Compatible Functions
763 ********************************
765 These functions are intended to be fully compatible with the
766 Berkeley MP library which is available on many BSD derived U*ix systems.
768 The original Berkeley MP library has a usage restriction: you cannot
769 use the same variable as both source and destination in a single
770 function call. The compatible functions in GNU MP do not share this
771 restriction--inputs and outputs may overlap.
773 It is not recommended that new programs are written using these
774 functions. Apart from the incomplete set of functions, the interface
775 for initializing `MINT' objects is more error prone, and the `pow'
776 function collides with `pow' in `libm.a'.
778 Include the header `mp.h' to get the definition of the necessary
779 types and functions. If you are on a BSD derived system, make sure to
780 include GNU `mp.h' if you are going to link the GNU `libmp.a' to you
781 program. This means that you probably need to give the -I<dir> option
782 to the compiler, where <dir> is the directory where you have GNU `mp.h'.
784 - Function: MINT * itom (signed short int INITIAL_VALUE)
785 Allocate an integer consisting of a `MINT' object and dynamic limb
786 space. Initialize the integer to INITIAL_VALUE. Return a pointer
787 to the `MINT' object.
789 - Function: MINT * xtom (char *INITIAL_VALUE)
790 Allocate an integer consisting of a `MINT' object and dynamic limb
791 space. Initialize the integer from INITIAL_VALUE, a hexadecimal,
792 '\0'-terminate C string. Return a pointer to the `MINT' object.
794 - Function: void move (MINT *SRC, MINT *DEST)
795 Set DEST to SRC by copying. Both variables must be previously
798 - Function: void madd (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION)
799 Add SRC_1 and SRC_2 and put the sum in DESTINATION.
801 - Function: void msub (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION)
802 Subtract SRC_2 from SRC_1 and put the difference in DESTINATION.
804 - Function: void mult (MINT *SRC_1, MINT *SRC_2, MINT *DESTINATION)
805 Multiply SRC_1 and SRC_2 and put the product in DESTINATION.
807 - Function: void mdiv (MINT *DIVIDEND, MINT *DIVISOR, MINT *QUOTIENT,
809 - Function: void sdiv (MINT *DIVIDEND, signed short int DIVISOR, MINT
810 *QUOTIENT, signed short int *REMAINDER)
811 Set QUOTIENT to DIVIDEND/DIVISOR, and REMAINDER to DIVIDEND mod
812 DIVISOR. The quotient is rounded towards zero; the remainder has
813 the same sign as the dividend unless it is zero.
815 Some implementations of these functions work differently--or not
816 at all--for negative arguments.
818 - Function: void msqrt (MINT *OPERAND, MINT *ROOT, MINT *REMAINDER)
819 Set ROOT to the truncated integer part of the square root of
820 OPERAND. Set REMAINDER to OPERAND-ROOT*ROOT, (i.e., zero if
821 OPERAND is a perfect square).
823 If ROOT and REMAINDER are the same variable, the results are
826 - Function: void pow (MINT *BASE, MINT *EXP, MINT *MOD, MINT *DEST)
827 Set DEST to (BASE raised to EXP) modulo MOD.
829 - Function: void rpow (MINT *BASE, signed short int EXP, MINT *DEST)
830 Set DEST to BASE raised to EXP.
832 - Function: void gcd (MINT *OPERAND1, MINT *OPERAND2, MINT *RES)
833 Set RES to the greatest common divisor of OPERAND1 and OPERAND2.
835 - Function: int mcmp (MINT *OPERAND1, MINT *OPERAND2)
836 Compare OPERAND1 and OPERAND2. Return a positive value if
837 OPERAND1 > OPERAND2, zero if OPERAND1 = OPERAND2, and a negative
838 value if OPERAND1 < OPERAND2.
840 - Function: void min (MINT *DEST)
841 Input a decimal string from `stdin', and put the read integer in
842 DEST. SPC and TAB are allowed in the number string, and are
845 - Function: void mout (MINT *SRC)
846 Output SRC to `stdout', as a decimal string. Also output a
849 - Function: char * mtox (MINT *OPERAND)
850 Convert OPERAND to a hexadecimal string, and return a pointer to
851 the string. The returned string is allocated using the default
852 memory allocation function, `malloc' by default.
854 - Function: void mfree (MINT *OPERAND)
855 De-allocate, the space used by OPERAND. *This function should
856 only be passed a value returned by `itom' or `xtom'.*
859 File: gmp.info, Node: Custom Allocation, Next: Contributors, Prev: BSD Compatible Functions, Up: Top
864 By default, the MP functions use `malloc', `realloc', and `free' for
865 memory allocation. If `malloc' or `realloc' fails, the MP library
866 terminates execution after printing a fatal error message to standard
869 For some applications, you may wish to allocate memory in other
870 ways, or you may not want to have a fatal error when there is no more
871 memory available. To accomplish this, you can specify alternative
872 memory allocation functions.
874 - Function: void mp_set_memory_functions (
875 void *(*ALLOC_FUNC_PTR) (size_t),
876 void *(*REALLOC_FUNC_PTR) (void *, size_t, size_t),
877 void (*FREE_FUNC_PTR) (void *, size_t))
878 Replace the current allocation functions from the arguments. If
879 an argument is NULL, the corresponding default function is
882 *Make sure to call this function in such a way that there are no
883 active MP objects that were allocated using the previously active
884 allocation function! Usually, that means that you have to call
885 this function before any other MP function.*
887 The functions you supply should fit the following declarations:
889 - Function: void * allocate_function (size_t ALLOC_SIZE)
890 This function should return a pointer to newly allocated space
891 with at least ALLOC_SIZE storage units.
893 - Function: void * reallocate_function (void *PTR, size_t OLD_SIZE,
895 This function should return a pointer to newly allocated space of
896 at least NEW_SIZE storage units, after copying at least the first
897 OLD_SIZE storage units from PTR. It should also de-allocate the
900 You can assume that the space at PTR was formerly returned from
901 `allocate_function' or `reallocate_function', for a request for
902 OLD_SIZE storage units.
904 - Function: void deallocate_function (void *PTR, size_t SIZE)
905 De-allocate the space pointed to by PTR.
907 You can assume that the space at PTR was formerly returned from
908 `allocate_function' or `reallocate_function', for a request for
911 (A "storage unit" is the unit in which the `sizeof' operator returns
912 the size of an object, normally an 8 bit byte.)
915 File: gmp.info, Node: Contributors, Next: References, Prev: Custom Allocation, Up: Top
920 I would like to thank Gunnar Sjoedin and Hans Riesel for their help
921 with mathematical problems, Richard Stallman for his help with design
922 issues and for revising the first version of this manual, Brian Beuning
923 and Doug Lea for their testing of early versions of the library.
925 John Amanatides of York University in Canada contributed the function
926 `mpz_probab_prime_p'.
928 Paul Zimmermann of Inria sparked the development of GMP 2, with his
929 comparisons between bignum packages.
931 Ken Weber (Kent State University, Universidade Federal do Rio Grande
932 do Sul) contributed `mpz_gcd', `mpz_divexact', `mpn_gcd', and
933 `mpn_bdivmod', partially supported by CNPq (Brazil) grant 301314194-2.
935 Per Bothner of Cygnus Support helped to set up MP to use Cygnus'
936 configure. He has also made valuable suggestions and tested numerous
937 intermediary releases.
939 Joachim Hollman was involved in the design of the `mpf' interface,
940 and in the `mpz' design revisions for version 2.
942 Bennet Yee contributed the functions `mpz_jacobi' and `mpz_legendre'.
944 Andreas Schwab contributed the files `mpn/m68k/lshift.S' and
947 The development of floating point functions of GNU MP 2, were
948 supported in part by the ESPRIT-BRA (Basic Research Activities) 6846
949 project POSSO (POlynomial System SOlving).
951 GNU MP 2 was finished and released by TMG Datakonsult,
952 Sodermannagatan 5, 116 23 STOCKHOLM, SWEDEN, in cooperation with the
953 IDA Center for Computing Sciences, USA.
956 File: gmp.info, Node: References, Prev: Contributors, Up: Top
961 * Donald E. Knuth, "The Art of Computer Programming", vol 2,
962 "Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981.
964 * John D. Lipson, "Elements of Algebra and Algebraic Computing", The
965 Benjamin Cummings Publishing Company Inc, 1981.
967 * Richard M. Stallman, "Using and Porting GCC", Free Software
970 * Peter L. Montgomery, "Modular Multiplication Without Trial
971 Division", in Mathematics of Computation, volume 44, number 170,
974 * Torbjorn Granlund and Peter L. Montgomery, "Division by Invariant
975 Integers using Multiplication", in Proceedings of the SIGPLAN
976 PLDI'94 Conference, June 1994.
978 * Tudor Jebelean, "An algorithm for exact division", Journal of
979 Symbolic Computation, v. 15, 1993, pp. 169-180.
981 * Kenneth Weber, "The accelerated integer GCD algorithm", ACM
982 Transactions on Mathematical Software, v. 21 (March), 1995, pp.
986 File: gmp.info, Node: Concept Index, Up: Top
994 * mp.h: BSD Compatible Functions.
995 * Arithmetic functions <1>: Float Arithmetic.
996 * Arithmetic functions: Integer Arithmetic.
997 * Bit manipulation functions: Integer Logic and Bit Fiddling.
998 * BSD MP compatible functions: BSD Compatible Functions.
999 * Comparison functions: Float Comparison.
1000 * Conditions for copying GNU MP: Copying.
1001 * Conversion functions <1>: Converting Integers.
1002 * Conversion functions: Converting Floats.
1003 * Copying conditions: Copying.
1004 * Float arithmetic functions: Float Arithmetic.
1005 * Float assignment functions: Assigning Floats.
1006 * Float comparisons functions: Float Comparison.
1007 * Float functions: Floating-point Functions.
1008 * Float input and output functions: I/O of Floats.
1009 * Floating-point functions: Floating-point Functions.
1010 * Floating-point number: MP Basics.
1011 * I/O functions <1>: I/O of Floats.
1012 * I/O functions: I/O of Integers.
1013 * Initialization and assignment functions <1>: Simultaneous Float Init & Assign.
1014 * Initialization and assignment functions: Simultaneous Integer Init & Assign.
1015 * Input functions <1>: I/O of Integers.
1016 * Input functions: I/O of Floats.
1017 * Installation: Installing MP.
1018 * Integer: MP Basics.
1019 * Integer arithmetic functions: Integer Arithmetic.
1020 * Integer assignment functions: Assigning Integers.
1021 * Integer conversion functions: Converting Integers.
1022 * Integer functions: Integer Functions.
1023 * Integer input and output functions: I/O of Integers.
1025 * Logical functions: Integer Logic and Bit Fiddling.
1026 * Low-level functions: Low-level Functions.
1027 * Miscellaneous float functions: Miscellaneous Float Functions.
1028 * Miscellaneous integer functions: Miscellaneous Integer Functions.
1029 * Output functions <1>: I/O of Floats.
1030 * Output functions: I/O of Integers.
1031 * Rational number: MP Basics.
1032 * Rational number functions: Rational Number Functions.
1033 * Reporting bugs: Reporting Bugs.
1034 * User-defined precision: Floating-point Functions.