Annotation of OpenXM_contrib/gmp/gmp.info-2, Revision 1.1.1.1
1.1 maekawa 1: This is Info file gmp.info, produced by Makeinfo-1.64 from the input
2: file gmp.texi.
3:
4: START-INFO-DIR-ENTRY
5: * gmp: (gmp.info). GNU Multiple Precision Arithmetic Library.
6: END-INFO-DIR-ENTRY
7:
8: This file documents GNU MP, a library for arbitrary-precision
9: arithmetic.
10:
11: Copyright (C) 1991, 1993, 1994, 1995, 1996 Free Software Foundation,
12: Inc.
13:
14: Permission is granted to make and distribute verbatim copies of this
15: manual provided the copyright notice and this permission notice are
16: preserved on all copies.
17:
18: Permission is granted to copy and distribute modified versions of
19: this manual under the conditions for verbatim copying, provided that
20: the entire resulting derived work is distributed under the terms of a
21: permission notice identical to this one.
22:
23: Permission is granted to copy and distribute translations of this
24: manual into another language, under the above conditions for modified
25: versions, except that this permission notice may be stated in a
26: translation approved by the Foundation.
27:
28:
29: File: gmp.info, Node: Floating-point Functions, Next: Low-level Functions, Prev: Rational Number Functions, Up: Top
30:
31: Floating-point Functions
32: ************************
33:
34: This is a description of the *preliminary* interface for
35: floating-point arithmetic in GNU MP 2.
36:
37: The floating-point functions expect arguments of type `mpf_t'.
38:
39: The MP floating-point functions have an interface that is similar to
40: the MP integer functions. The function prefix for floating-point
41: operations is `mpf_'.
42:
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
49: ignored.
50:
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.
58:
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.
63:
64: * Menu:
65:
66: * Initializing Floats::
67: * Assigning Floats::
68: * Simultaneous Float Init & Assign::
69: * Converting Floats::
70: * Float Arithmetic::
71: * Float Comparison::
72: * I/O of Floats::
73: * Miscellaneous Float Functions::
74:
75:
76: File: gmp.info, Node: Initializing Floats, Next: Assigning Floats, Up: Floating-point Functions
77:
78: Initialization and Assignment Functions
79: =======================================
80:
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.
85:
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
88: purpose.
89:
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'.
96:
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.
101:
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.
105:
106: Here is an example on how to initialize floating-point variables:
107: {
108: mpf_t x, y;
109: mpf_init (x); /* use default precision */
110: mpf_init2 (y, 256); /* precision *at least* 256 bits */
111: ...
112: /* Unless the program is about to exit, do ... */
113: mpf_clear (x);
114: mpf_clear (y);
115: }
116:
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
121: numbers.
122:
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.
127:
128: - Function: unsigned long int mpf_get_prec (mpf_t OP)
129: Return the precision actually used for assignments of OP.
130:
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'.
137:
138:
139: File: gmp.info, Node: Assigning Floats, Next: Simultaneous Float Init & Assign, Prev: Initializing Floats, Up: Floating-point Functions
140:
141: Assignment Functions
142: --------------------
143:
144: These functions assign new values to already initialized floats
145: (*note Initializing Floats::.).
146:
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.
154:
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.
161:
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
164: decimal.
165:
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.
169:
170: White space is allowed in the string, and is simply ignored.
171:
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.
174:
175:
176: File: gmp.info, Node: Simultaneous Float Init & Assign, Next: Converting Floats, Prev: Assigning Floats, Up: Floating-point Functions
177:
178: Combined Initialization and Assignment Functions
179: ------------------------------------------------
180:
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...'
184:
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!
189:
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.
195:
196: The precision of ROP will be taken from the active default
197: precision, as set by `mpf_set_default_prec'.
198:
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.
202:
203: Note that ROP is initialized even if an error occurs. (I.e., you
204: have to call `mpf_clear' for it.)
205:
206: The precision of ROP will be taken from the active default
207: precision, as set by `mpf_set_default_prec'.
208:
209:
210: File: gmp.info, Node: Converting Floats, Next: Float Arithmetic, Prev: Simultaneous Float Init & Assign, Up: Floating-point Functions
211:
212: Conversion Functions
213: ====================
214:
215: - Function: double mpf_get_d (mpf_t OP)
216: Convert OP to a double.
217:
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
223: representable by OP.
224:
225: If STR is NULL, space for the mantissa is allocated using the
226: default allocation function, and a pointer to the string is
227: returned.
228:
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
232: character.
233:
234: The exponent is written through the pointer EXPPTR.
235:
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.
241:
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
245: written at EXPPTR.
246:
247:
248: File: gmp.info, Node: Float Arithmetic, Next: Float Comparison, Prev: Converting Floats, Up: Floating-point Functions
249:
250: Arithmetic Functions
251: ====================
252:
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
255: OP2)
256: Set ROP to OP1 + OP2.
257:
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
260: OP2)
261: - Function: void mpf_sub_ui (mpf_t ROP, mpf_t OP1, unsigned long int
262: OP2)
263: Set ROP to OP1 - OP2.
264:
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
267: OP2)
268: Set ROP to OP1 times OP2.
269:
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.
275:
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
278: OP2)
279: - Function: void mpf_div_ui (mpf_t ROP, mpf_t OP1, unsigned long int
280: OP2)
281: Set ROP to OP1/OP2.
282:
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.
286:
287: - Function: void mpf_neg (mpf_t ROP, mpf_t OP)
288: Set ROP to -OP.
289:
290: - Function: void mpf_abs (mpf_t ROP, mpf_t OP)
291: Set ROP to the absolute value of OP.
292:
293: - Function: void mpf_mul_2exp (mpf_t ROP, mpf_t OP1, unsigned long int
294: OP2)
295: Set ROP to OP1 times 2 raised to OP2.
296:
297: - Function: void mpf_div_2exp (mpf_t ROP, mpf_t OP1, unsigned long int
298: OP2)
299: Set ROP to OP1 divided by 2 raised to OP2.
300:
301:
302: File: gmp.info, Node: Float Comparison, Next: I/O of Floats, Prev: Float Arithmetic, Up: Floating-point Functions
303:
304: Comparison Functions
305: ====================
306:
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.
312:
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.
316:
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
319: result in ROP.
320:
321: - Macro: int mpf_sgn (mpf_t OP)
322: Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.
323:
324: This function is actually implemented as a macro. It evaluates its
325: arguments multiple times.
326:
327:
328: File: gmp.info, Node: I/O of Floats, Next: Miscellaneous Float Functions, Prev: Float Comparison, Up: Floating-point Functions
329:
330: Input and Output Functions
331: ==========================
332:
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.
337:
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.
341:
342: - Function: size_t mpf_out_str (FILE *STREAM, int BASE, size_t
343: N_DIGITS, mpf_t OP)
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.
348:
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
352: delimiter.
353:
354: Return the number of bytes written, or if an error occurred,
355: return 0.
356:
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.
364:
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
367: decimal.
368:
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.
372:
373: Return the number of bytes read, or if an error occurred, return 0.
374:
375:
376: File: gmp.info, Node: Miscellaneous Float Functions, Prev: I/O of Floats, Up: Floating-point Functions
377:
378: Miscellaneous Functions
379: =======================
380:
381: - Function: void mpf_random2 (mpf_t ROP, mp_size_t MAX_SIZE, mp_exp_t
382: MAX_EXP)
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.
390:
391:
392: File: gmp.info, Node: Low-level Functions, Next: BSD Compatible Functions, Prev: Floating-point Functions, Up: Top
393:
394: Low-level Functions
395: *******************
396:
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.
399:
400: These functions start with the prefix `mpn_'.
401:
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.
408:
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.
413:
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.
417:
418: A common requirement for all functions is that each source area
419: needs at least one limb. No size argument may be zero.
420:
421: The `mpn' functions is the base for the implementation of the `mpz_',
422: `mpf_', and `mpq_' functions.
423:
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
426: SIZE limbs.
427:
428: cy = mpn_add_n (dest_ptr, src1_ptr, src2_ptr, size)
429:
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}.
433:
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,
438: either 0 or 1.
439:
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
444: optimal speed.
445:
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
450: 0 or 1.
451:
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,
454: mp_size_t SRC2_SIZE)
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.
458:
459: This function requires that SRC1_SIZE is greater than or equal to
460: SRC2_SIZE.
461:
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.
467:
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.
471:
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,
476: either 0 or 1.
477:
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,
480: mp_size_t SRC2_SIZE)
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.
484:
485: This function requires that SRC1_SIZE is greater than or equal to
486: SRC2_SIZE.
487:
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.
492:
493: The destination has to have space for 2SIZE limbs, even if the
494: significant result might be one limb smaller.
495:
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.
501:
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.
505:
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.
509:
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.
516:
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.
520:
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.
527:
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.
531:
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,
534: mp_size_t SRC2_SIZE)
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
537: the result.
538:
539: The destination has to have space for SRC1_SIZE + SRC1_SIZE limbs,
540: even if the result might be one limb smaller.
541:
542: This function requires that SRC1_SIZE is greater than or equal to
543: SRC2_SIZE. The destination must be distinct from either input
544: operands.
545:
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,
548: mp_size_t S3SIZE)
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.
552:
553: In addition to an integer quotient, XSIZE fraction limbs are
554: developed, and stored after the integral limbs. For most usages,
555: XSIZE will be zero.
556:
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.
559:
560: If the quotient is not needed, pass RS2P + S3SIZE as R1P. Aside
561: from that special case, no overlap between arguments is permitted.
562:
563: Return the most significant limb of the quotient, either 0 or 1.
564:
565: The area at R1P needs to be RS2SIZE - S3SIZE + XSIZE limbs large.
566:
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.
571:
572: In addition to an integer quotient, XSIZE fraction limbs are
573: developed, and stored after the integral limbs. For most usages,
574: XSIZE will be zero.
575:
576: The areas at R1P and S2P have to be identical or completely
577: separate, not partially overlapping.
578:
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.*
583:
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.*
588:
589: - Function: mp_limb_t mpn_mod_1 (mp_limb_t * S1P, mp_size_t S1SIZE,
590: mp_limb_t S2LIMB)
591: Divide {S1P, S1SIZE} by S2LIMB, and return the remainder.
592:
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.*
597:
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.
604:
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.
609:
610: This function requires that S1SIZE * BITS_PER_MP_LIMB >= D, and
611: that {S2P, S2SIZE} is odd.
612:
613: *This interface is preliminary. It might change incompatibly in
614: future revisions.*
615:
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
618: COUNT)
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.
623:
624: Overlapping of the destination space and the source space is
625: allowed in this function, provided DEST_PTR >= SRC_PTR.
626:
627: This function is written in assembly for most targets.
628:
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
631: COUNT)
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.
636:
637: Overlapping of the destination space and the source space is
638: allowed in this function, provided DEST_PTR <= SRC_PTR.
639:
640: This function is written in assembly for most targets.
641:
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.
647:
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,
650: mp_size_t SRC2_SIZE)
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.
655:
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}.
658:
659: *This interface is preliminary. It might change incompatibly in
660: future revisions.*
661:
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
666: different from 0.
667:
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
670: S2SIZE)
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.
675:
676: *This interface is preliminary. It might change incompatibly in
677: future revisions.*
678:
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.
683:
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.
686:
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
689: overlapping.
690:
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.
693:
694: *This interface is preliminary. It might change incompatibly in
695: future revisions.*
696:
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.
703:
704: The area at S1P is clobbered.
705:
706: Return the number of characters in STR.
707:
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.
710:
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.
715:
716: Return the number of limbs stored in R1P.
717:
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.
721:
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
724: return.
725:
726: *This interface is preliminary. It might change incompatibly in
727: future revisions.*
728:
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.
732:
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
735: return.
736:
737: *This interface is preliminary. It might change incompatibly in
738: future revisions.*
739:
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.
743:
744: The generated random numbers are intended for testing the
745: correctness of the implementation of the `mpn' routines.
746:
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}.
750:
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}.
754:
755: - Function: int mpn_perfect_square_p (const mp_limb_t * S1P, mp_size_t
756: SIZE)
757: Return non-zero iff {S1P, SIZE} is a perfect square.
758:
759:
760: File: gmp.info, Node: BSD Compatible Functions, Next: Custom Allocation, Prev: Low-level Functions, Up: Top
761:
762: Berkeley MP Compatible Functions
763: ********************************
764:
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.
767:
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.
772:
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'.
777:
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'.
783:
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.
788:
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.
793:
794: - Function: void move (MINT *SRC, MINT *DEST)
795: Set DEST to SRC by copying. Both variables must be previously
796: initialized.
797:
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.
800:
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.
803:
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.
806:
807: - Function: void mdiv (MINT *DIVIDEND, MINT *DIVISOR, MINT *QUOTIENT,
808: MINT *REMAINDER)
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.
814:
815: Some implementations of these functions work differently--or not
816: at all--for negative arguments.
817:
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).
822:
823: If ROOT and REMAINDER are the same variable, the results are
824: undefined.
825:
826: - Function: void pow (MINT *BASE, MINT *EXP, MINT *MOD, MINT *DEST)
827: Set DEST to (BASE raised to EXP) modulo MOD.
828:
829: - Function: void rpow (MINT *BASE, signed short int EXP, MINT *DEST)
830: Set DEST to BASE raised to EXP.
831:
832: - Function: void gcd (MINT *OPERAND1, MINT *OPERAND2, MINT *RES)
833: Set RES to the greatest common divisor of OPERAND1 and OPERAND2.
834:
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.
839:
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
843: ignored.
844:
845: - Function: void mout (MINT *SRC)
846: Output SRC to `stdout', as a decimal string. Also output a
847: newline.
848:
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.
853:
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'.*
857:
858:
859: File: gmp.info, Node: Custom Allocation, Next: Contributors, Prev: BSD Compatible Functions, Up: Top
860:
861: Custom Allocation
862: *****************
863:
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
867: error.
868:
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.
873:
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
880: retained.
881:
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.*
886:
887: The functions you supply should fit the following declarations:
888:
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.
892:
893: - Function: void * reallocate_function (void *PTR, size_t OLD_SIZE,
894: size_t NEW_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
898: space at PTR.
899:
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.
903:
904: - Function: void deallocate_function (void *PTR, size_t SIZE)
905: De-allocate the space pointed to by PTR.
906:
907: You can assume that the space at PTR was formerly returned from
908: `allocate_function' or `reallocate_function', for a request for
909: SIZE storage units.
910:
911: (A "storage unit" is the unit in which the `sizeof' operator returns
912: the size of an object, normally an 8 bit byte.)
913:
914:
915: File: gmp.info, Node: Contributors, Next: References, Prev: Custom Allocation, Up: Top
916:
917: Contributors
918: ************
919:
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.
924:
925: John Amanatides of York University in Canada contributed the function
926: `mpz_probab_prime_p'.
927:
928: Paul Zimmermann of Inria sparked the development of GMP 2, with his
929: comparisons between bignum packages.
930:
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.
934:
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.
938:
939: Joachim Hollman was involved in the design of the `mpf' interface,
940: and in the `mpz' design revisions for version 2.
941:
942: Bennet Yee contributed the functions `mpz_jacobi' and `mpz_legendre'.
943:
944: Andreas Schwab contributed the files `mpn/m68k/lshift.S' and
945: `mpn/m68k/rshift.S'.
946:
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).
950:
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.
954:
955:
956: File: gmp.info, Node: References, Prev: Contributors, Up: Top
957:
958: References
959: **********
960:
961: * Donald E. Knuth, "The Art of Computer Programming", vol 2,
962: "Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981.
963:
964: * John D. Lipson, "Elements of Algebra and Algebraic Computing", The
965: Benjamin Cummings Publishing Company Inc, 1981.
966:
967: * Richard M. Stallman, "Using and Porting GCC", Free Software
968: Foundation, 1995.
969:
970: * Peter L. Montgomery, "Modular Multiplication Without Trial
971: Division", in Mathematics of Computation, volume 44, number 170,
972: April 1985.
973:
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.
977:
978: * Tudor Jebelean, "An algorithm for exact division", Journal of
979: Symbolic Computation, v. 15, 1993, pp. 169-180.
980:
981: * Kenneth Weber, "The accelerated integer GCD algorithm", ACM
982: Transactions on Mathematical Software, v. 21 (March), 1995, pp.
983: 111-122.
984:
985:
986: File: gmp.info, Node: Concept Index, Up: Top
987:
988: Concept Index
989: *************
990:
991: * Menu:
992:
993: * gmp.h: MP Basics.
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.
1024: * Limb: MP Basics.
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.
1035:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to gmp.info-2 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gmp