Annotation of OpenXM_contrib/gmp/mpfr/mpfr.info, Revision 1.1.1.1
1.1 ohara 1: This is mpfr.info, produced by makeinfo version 4.2 from mpfr.texi.
2:
3: START-INFO-DIR-ENTRY
4: * mpfr: (mpfr.info). Multiple Precision Floating-Point Reliable Library.
5: END-INFO-DIR-ENTRY
6:
7: This file documents MPFR, a library for reliable multiple precision
8: floating-point arithmetic
9:
10: Copyright (C) 1999-2002, Free Software Foundation.
11:
12: Permission is granted to make and distribute verbatim copies of this
13: manual provided the copyright notice and this permission notice are
14: preserved on all copies.
15:
16: Permission is granted to copy and distribute modified versions of
17: this manual under the conditions for verbatim copying, provided that
18: the entire resulting derived work is distributed under the terms of a
19: permission notice identical to this one.
20:
21: Permission is granted to copy and distribute translations of this
22: manual into another language, under the above conditions for modified
23: versions, except that this permission notice may be stated in a
24: translation approved by the Foundation.
25:
26:
27: File: mpfr.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
28:
29: MPFR
30: ****
31:
32: This manual documents how to install and use the Multiple Precision
33: Floating-Point Reliable Library, version 2.0.1
34:
35: * Menu:
36:
37: * Copying:: GMP Copying Conditions (LGPL).
38: * Introduction to MPFR:: Brief introduction to MPFR.
39: * Installing MPFR:: How to configure and compile the MPFR library.
40: * MPFR Basics:: What every MPFR user should now.
41: * Reporting Bugs:: How to usefully report bugs.
42: * Floating-point Functions:: Functions for arithmetic on floats.
43:
44: * Contributors::
45: * References::
46: * Concept Index::
47: * Function Index::
48:
49:
50: File: mpfr.info, Node: Copying, Next: Introduction to MPFR, Prev: Top, Up: Top
51:
52: MPFR Copying Conditions
53: ***********************
54:
55: This library is "free"; this means that everyone is free to use it
56: and free to redistribute it on a free basis. The library is not in the
57: public domain; it is copyrighted and there are restrictions on its
58: distribution, but these restrictions are designed to permit everything
59: that a good cooperating citizen would want to do. What is not allowed
60: is to try to prevent others from further sharing any version of this
61: library that they might get from you.
62:
63: Specifically, we want to make sure that you have the right to give
64: away copies of the library, that you receive source code or else can
65: get it if you want it, that you can change this library or use pieces
66: of it in new free programs, and that you know you can do these things.
67:
68: To make sure that everyone has such rights, we have to forbid you to
69: deprive anyone else of these rights. For example, if you distribute
70: copies of the MPFR library, you must give the recipients all the rights
71: that you have. You must make sure that they, too, receive or can get
72: the source code. And you must tell them their rights.
73:
74: Also, for our own protection, we must make certain that everyone
75: finds out that there is no warranty for the MPFR library. If it is
76: modified by someone else and passed on, we want their recipients to
77: know that what they have is not what we distributed, so that any
78: problems introduced by others will not reflect on our reputation.
79:
80: The precise conditions of the license for the MPFR library are found
81: in the Lesser General Public License that accompanies the source code.
82: See the file COPYING.LIB.
83:
84:
85: File: mpfr.info, Node: Introduction to MPFR, Next: Installing MPFR, Prev: Copying, Up: Top
86:
87: Introduction to MPFR
88: ********************
89:
90: MPFR is a portable library written in C for arbitrary precision
91: arithmetic on reliable floating-point numbers. It is based on the GNU
92: MP library. It aims to extend the class of floating-point numbers
93: provided by the GNU MP library by "reliable" floating-point numbers. It
94: may replace the GNU MP floating-point numbers in a future release. The
95: main differences with the `mpf' class are:
96:
97: * the `mpfr' code is portable, i.e. the result of any operation does
98: not depend (or should not) on the machine word size
99: `mp_bits_per_limb' (32 or 64 on most machines);
100:
101: * the precision in bits can be set exactly to any valid value for
102: each variable (including very small precision);
103:
104: * `mpfr' provides the four rounding modes from the IEEE 754 standard.
105:
106: In particular, with a precision of 53 bits, `mpfr' should be able to
107: exactly reproduce all computations with double-precision machine
108: floating-point numbers (`double' type in C), except the default
109: exponent range is much wider and subnormal numbers are not implemented.
110:
111: This version of MPFR is released under the GNU Lesser General Public
112: License. It is permitted to link MPFR to non-free programs, as long as
113: when distributing them the MPFR source code and a means to re-link with
114: a modified MPFR is provided.
115:
116: How to use this Manual
117: ======================
118:
119: Everyone should read *Note MPFR Basics::. If you need to install
120: the library yourself, you need to read *Note Installing MPFR::, too.
121:
122: The rest of the manual can be used for later reference, although it
123: is probably a good idea to glance through it.
124:
125:
126: File: mpfr.info, Node: Installing MPFR, Next: Reporting Bugs, Prev: Introduction to MPFR, Up: Top
127:
128: Installing MPFR
129: ***************
130:
131: To build MPFR, you first have to install GNU MP (version 4.0.1 or
132: higher) on your computer. You need a C compiler, preferably GCC, but
133: any reasonable compiler should work. And you need a standard Unix
134: `make' program, plus some other standard Unix utility programs.
135:
136: Here are the steps needed to install the library on Unix systems
137: (more details are provided in the `INSTALL' file):
138:
139: 1. In most cases, `./configure --with-gmp=/usr/local/gmp' should work,
140: where the directory `/usr/local/gmp' is where you have installed
141: GNU MP. When you install GNU MP, you have to copy the files
142: `config.h', `gmp-impl.h', `gmp-mparam.h' and `longlong.h' from the
143: GNU MP source directory to `/usr/local/gmp/include'; these
144: additional files are needed by MPFR. If you get error messages,
145: you might check that you use the same compiler and compile options
146: as for GNU MP (see the `INSTALL' file).
147:
148: 2. `make'
149:
150: This will compile MPFR, and create a library archive file
151: `libmpfr.a' in the working directory.
152:
153: 3. `make check'
154:
155: This will make sure MPFR was built correctly. If you get error
156: messages, please report this to `mpfr@loria.fr'. (*Note Reporting
157: Bugs::, for information on what to include in useful bug reports.)
158:
159: 4. `make install'
160:
161: This will copy the files `mpfr.h' and `mpf2mpfr.h', and
162: `libmpfr.a', to the directories `/usr/local/include' and
163: `/usr/local/lib' respectively (or if you passed the `--prefix'
164: option to `configure', to the directory given as argument to
165: `--prefix'). This will also install `mpfr.info' in
166: `/usr/local/info'.
167:
168: There are some other useful make targets:
169:
170: * `mpfr.dvi' or `dvi'
171:
172: Create a DVI version of the manual, in `mpfr.dvi'.
173:
174: * `mpfr.ps'
175:
176: Create a Postscript version of the manual, in `mpfr.ps'.
177:
178: * `clean'
179:
180: Delete all object files and archive files, but not the
181: configuration files.
182:
183: * `distclean'
184:
185: Delete all files not included in the distribution.
186:
187: * `uninstall' Delete all files copied by `make install'.
188:
189: Known Build Problems
190: ====================
191:
192: MPFR suffers from all bugs from the GNU MP library, plus many many
193: more.
194:
195: Please report other problems to `mpfr@loria.fr'. *Note Reporting
196: Bugs::. Some bug fixes are available on the MPFR web page
197: `http://www.loria.fr/projets/mpfr/' or `http://www.mpfr.org/'.
198:
199:
200: File: mpfr.info, Node: Reporting Bugs, Next: MPFR Basics, Prev: Installing MPFR, Up: Top
201:
202: Reporting Bugs
203: **************
204:
205: If you think you have found a bug in the MPFR library, first have a
206: look on the MPFR web page `http://www.loria.fr/projets/mpfr/' or
207: `http://www.mpfr.org/': perhaps this bug is already known, in which
208: case you will find a workaround for it. Otherwise, please investigate
209: and report it. We have made this library available to you, and it is
210: not to ask too much from you, to ask you to report the bugs that you
211: find.
212:
213: There are a few things you should think about when you put your bug
214: report together.
215:
216: You have to send us a test case that makes it possible for us to
217: reproduce the bug. Include instructions on how to run the test case.
218:
219: You also have to explain what is wrong; if you get a crash, or if
220: the results printed are incorrect and in that case, in what way.
221:
222: Please include compiler version information in your bug report.
223: This can be extracted using `cc -V' on some machines, or, if you're
224: using gcc, `gcc -v'. Also, include the output from `uname -a'.
225:
226: If your bug report is good, we will do our best to help you to get a
227: corrected version of the library; if the bug report is poor, we won't
228: do anything about it (aside of chiding you to send better bug reports).
229:
230: Send your bug report to: `mpfr@loria.fr'.
231:
232: If you think something in this manual is unclear, or downright
233: incorrect, or if the language needs to be improved, please send a note
234: to the same address.
235:
236:
237: File: mpfr.info, Node: MPFR Basics, Next: Floating-point Functions, Prev: Reporting Bugs, Up: Top
238:
239: MPFR Basics
240: ***********
241:
242: All declarations needed to use MPFR are collected in the include file
243: `mpfr.h'. It is designed to work with both C and C++ compilers. You
244: should include that file in any program using the MPFR library:
245:
246: `#include "mpfr.h"'
247:
248: Nomenclature and Types
249: ======================
250:
251: "Floating-point number" or "Float" for short, is an arbitrary precision
252: mantissa with a limited precision exponent. The C data type for such
253: objects is `mpfr_t'. A floating-point number can have three special
254: values: Not-a-Number (NaN) or plus or minus Infinity. NaN represents a
255: value which cannot be represented in the floating-point format, like 0
256: divided by 0, or Infinity minus Infinity.
257:
258: The "Precision" is the number of bits used to represent the mantissa of
259: a floating-point number; the corresponding C data type is `mp_prec_t'.
260: The precision can be any integer between `MPFR_PREC_MIN' and
261: `MPFR_PREC_MAX'. In the current implementation, `MPFR_PREC_MIN' is
262: equal to 2 and `MPFR_PREC_MAX' is equal to `ULONG_MAX'.
263:
264: The "rounding mode" specifies the way to round the result of a
265: floating-point operation, in case the exact result can not be
266: represented exactly in the destination mantissa; the corresponding C
267: data type is `mp_rnd_t'.
268:
269: A "limb" means the part of a multi-precision number that fits in a
270: single word. (We chose this word because a limb of the human body is
271: analogous to a digit, only larger, and containing several digits.)
272: Normally a limb contains 32 or 64 bits. The C data type for a limb is
273: `mp_limb_t'.
274:
275: Function Classes
276: ================
277:
278: There is only one class of functions in the MPFR library:
279:
280: 1. Functions for floating-point arithmetic, with names beginning with
281: `mpfr_'. The associated type is `mpfr_t'.
282:
283: MPFR Variable Conventions
284: =========================
285:
286: As a general rule, all MPFR functions expect output arguments before
287: input arguments. This notation is based on an analogy with the
288: assignment operator.
289:
290: MPFR allows you to use the same variable for both input and output
291: in the same expression. For example, the main function for
292: floating-point multiplication, `mpfr_mul', can be used like this:
293: `mpfr_mul (x, x, x, rnd_mode)'. This computes the square of X with
294: rounding mode `rnd_mode' and puts the result back in X.
295:
296: Before you can assign to an MPFR variable, you need to initialize it
297: by calling one of the special initialization functions. When you're
298: done with a variable, you need to clear it out, using one of the
299: functions for that purpose.
300:
301: A variable should only be initialized once, or at least cleared out
302: between each initialization. After a variable has been initialized, it
303: may be assigned to any number of times.
304:
305: For efficiency reasons, avoid to initialize and clear out a variable
306: in loops. Instead, initialize it before entering the loop, and clear
307: it out after the loop has exited.
308:
309: You don't need to be concerned about allocating additional space for
310: MPFR variables, since any variable has a mantissa of fixed size. Hence
311: unless you change its precision, or clear and reinitialize it, a
312: floating-point variable will have the same allocated space during all
313: its life.
314:
315: Compatibility with MPF
316: ======================
317:
318: A header file `mpf2mpfr.h' is included in the distribution of MPFR
319: for compatibility with the GNU MP class MPF. After inserting the
320: following two lines after the `#include "gmp.h"' line,
321:
322: `#include "mpfr.h"'
323:
324: `#include "mpf2mpfr.h"'
325:
326: any program written for MPF can be linked directly with MPFR without
327: any changes. All operations are then performed with the default MPFR
328: rounding mode, which can be reset with `mpfr_set_default_rounding_mode'.
329:
330: - Global Variable: mp_rnd_t __gmp_default_rounding_mode
331: The default rounding mode (to nearest initially).
332:
333: Getting the Latest Version of MPFR
334: ==================================
335:
336: The latest version of MPFR is available from
337: `http://www.loria.fr/projets/mpfr/' or `http://www.mpfr.org/'.
338:
339:
340: File: mpfr.info, Node: Floating-point Functions, Next: Contributors, Prev: MPFR Basics, Up: Top
341:
342: Floating-point Functions
343: ************************
344:
345: The floating-point functions expect arguments of type `mpfr_t'.
346:
347: The MPFR floating-point functions have an interface that is similar
348: to the GNU MP integer functions. The function prefix for
349: floating-point operations is `mpfr_'.
350:
351: There is one significant characteristic of floating-point numbers
352: that has motivated a difference between this function class and other
353: MPFR function classes: the inherent inexactness of floating-point
354: arithmetic. The user has to specify the precision of each variable. A
355: computation that assigns a variable will take place with the precision
356: of the assigned variable; the cost of that computation should not
357: depend from the precision of variables used as input on average.
358:
359: The precision of a calculation is defined as follows: Compute the
360: requested operation exactly (with "infinite precision"), and round the
361: result to the destination variable precision with the given rounding
362: mode. Even if the user has asked for a very high precision, MP will
363: not calculate with superfluous digits. For example, if two
364: low-precision numbers of nearly equal magnitude are added, the
365: precision of the result will be limited to what is required to
366: represent the result accurately.
367:
368: The MPFR floating-point functions are intended to be a smooth
369: extension of the IEEE P754 arithmetic. The results obtained on one
370: computer should not differ from the results obtained on a computer with
371: a different word size.
372:
373: * Menu:
374:
375: * Rounding Modes::
376: * Exceptions::
377: * Initializing Floats::
378: * Assigning Floats::
379: * Simultaneous Float Init & Assign::
380: * Converting Floats::
381: * Float Arithmetic::
382: * Float Comparison::
383: * I/O of Floats::
384: * Miscellaneous Float Functions::
385:
386:
387: File: mpfr.info, Node: Rounding Modes, Next: Exceptions, Prev: Floating-point Functions, Up: Floating-point Functions
388:
389: Rounding Modes
390: ==============
391:
392: The following four rounding modes are supported:
393: * `GMP_RNDN': round to nearest
394:
395: * `GMP_RNDZ': round towards zero
396:
397: * `GMP_RNDU': round towards plus infinity
398:
399: * `GMP_RNDD': round towards minus infinity
400: The `round to nearest' mode works as in the IEEE P754 standard: in
401: case the number to be rounded lies exactly in the middle of two
402: representable numbers, it is rounded to the one with the least
403: significant bit set to zero. For example, the number 5, which is
404: represented by (101) in binary, is rounded to (100)=4 with a precision
405: of two bits, and not to (110)=6. This rule avoids the "drift"
406: phenomenon mentioned by Knuth in volume 2 of The Art of Computer
407: Programming (section 4.2.2, pages 221-222).
408:
409: Most MPFR functions take as first argument the destination variable,
410: as second and following arguments the input variables, as last argument
411: a rounding mode, and have a return value of type `int'. If this value
412: is zero, it means that the value stored in the destination variable is
413: the exact result of the corresponding mathematical function. If the
414: returned value is positive (resp. negative), it means the value stored
415: in the destination variable is greater (resp. lower) than the exact
416: result. For example with the `GMP_RNDU' rounding mode, the returned
417: value is usually positive, except when the result is exact, in which
418: case it is zero. In the case of an infinite result, it is considered
419: as inexact when it was obtained by overflow, and exact otherwise. A
420: NaN result (Not-a-Number) always corresponds to an inexact return value.
421:
422: - Function: void mpfr_set_default_rounding_mode (mp_rnd_t RND)
423: Sets the default rounding mode to RND. The default rounding mode
424: is to nearest initially.
425:
426: - Function: int mpfr_round_prec (mpfr_t X, mp_rnd_t RND, mp_prec_t
427: PREC)
428: Rounds X according to RND with precision PREC, which may be
429: different from that of X. If PREC is greater or equal to the
430: precision of X, then new space is allocated for the mantissa, and
431: it is filled with zeroes. Otherwise, the mantissa is rounded to
432: precision PREC with the given direction. In both cases, the
433: precision of X is changed to PREC. The returned value is zero
434: when the result is exact, positive when it is greater than the
435: original value of X, and negative when it is smaller. The
436: precision PREC can be any integer between `MPFR_PREC_MIN' and
437: `MPFR_PREC_MAX'.
438:
439: - Function: void mpfr_set_machine_rnd_mode (mp_rnd_t RND)
440: Set the machine rounding mode to RND. This function is provided
441: only when the operating system supports the ISOC9X standard
442: interface for setting rounding modes (i.e. through the header file
443: <fenv.h>).
444:
445: - Function: char * mpfr_print_rnd_mode (mp_rnd_t RND)
446: Returns the input string (GMP_RNDD, GMP_RNDU, GMP_RNDN, GMP_RNDZ)
447: corresponding to the rounding mode RND or a null pointer if RND is
448: an invalid rounding mode.
449:
450:
451: File: mpfr.info, Node: Exceptions, Next: Initializing Floats, Prev: Rounding Modes, Up: Floating-point Functions
452:
453: Exceptions
454: ==========
455:
456: Note: Overflow handling is still experimental and currently
457: implemented very partially. If an overflow occurs internally at the
458: wrong place, anything can happen (crash, wrong results, etc).
459:
460: - Function: mp_exp_t mpfr_get_emin (void)
461: - Function: mp_exp_t mpfr_get_emax (void)
462: Return the (current) smallest and largest exponents allowed for a
463: floating-point variable.
464:
465: - Function: int mpfr_set_emin (mp_exp_t EXP)
466: - Function: int mpfr_set_emax (mp_exp_t EXP)
467: Set the smallest and largest exponents allowed for a
468: floating-point variable. Return a non-zero value when EXP is not
469: in the range accepted by the implementation (in that case the
470: smallest or largest exponent is not changed), and zero otherwise.
471: If the user changes the exponent range, it is her/his
472: responsibility to check that all current floating-point variables
473: are in the new allowed range (for example using `mpfr_check_range',
474: otherwise the subsequent behaviour will be undefined, in the sense
475: of the ISO C standard.
476:
477: - Function: int mpfr_check_range (mpfr_t X, mp_rnd_t RND)
478: Return zero if the exponent of X is in the current allowed range
479: (see `mpfr_get_emin' and `mpfr_get_emax'), otherwise reset X
480: according to the current floating-point system and the rounding
481: mode RND, and return a positive value if the rounded result is
482: larger than the original one, a negative value otherwise (the
483: result cannot be exact in that case).
484:
485: - Function: void mpfr_clear_underflow (void)
486: - Function: void mpfr_clear_overflow (void)
487: - Function: void mpfr_clear_nanflag (void)
488: - Function: void mpfr_clear_inexflag (void)
489: Clear the underflow, overflow, invalid, and inexact flags.
490:
491: - Function: void mpfr_clear_flags (void)
492: Clear all global flags (underflow, overflow, inexact, invalid).
493:
494: - Function: int mpfr_underflow_p (void)
495: - Function: int mpfr_overflow_p (void)
496: - Function: int mpfr_nanflag_p (void)
497: - Function: int mpfr_inexflag_p (void)
498: Return the corresponding (underflow, overflow, invalid, inexact)
499: flag, which is non-zero iff the flag is set.
500:
501:
502: File: mpfr.info, Node: Initializing Floats, Next: Assigning Floats, Prev: Exceptions, Up: Floating-point Functions
503:
504: Initialization and Assignment Functions
505: =======================================
506:
507: - Function: void mpfr_set_default_prec (mp_prec_t PREC)
508: Set the default precision to be *exactly* PREC bits. The
509: precision of a variable means the number of bits used to store its
510: mantissa. All subsequent calls to `mpfr_init' will use this
511: precision, but previously initialized variables are unaffected.
512: This default precision is set to 53 bits initially. The precision
513: can be any integer between `MPFR_PREC_MIN' and `MPFR_PREC_MAX'.
514:
515: - Function: mp_prec_t mpfr_get_default_prec ()
516: Returns the default MPFR precision in bits.
517:
518: An `mpfr_t' object must be initialized before storing the first
519: value in it. The functions `mpfr_init' and `mpfr_init2' are used for
520: that purpose.
521:
522: - Function: void mpfr_init (mpfr_t X)
523: Initialize X, and set its value to NaN. Normally, a variable
524: should be initialized once only or at least be cleared, using
525: `mpfr_clear', between initializations. The precision of X is the
526: default precision, which can be changed by a call to
527: `mpfr_set_default_prec'.
528:
529: - Function: void mpfr_init2 (mpfr_t X, mp_prec_t PREC)
530: Initialize X, set its precision to be *exactly* PREC bits, and set
531: its value to NaN. Normally, a variable should be initialized once
532: only or at least be cleared, using `mpfr_clear', between
533: initializations. To change the precision of a variable which has
534: already been initialized, use `mpfr_set_prec' instead. The
535: precision PREC can be any integer between `MPFR_PREC_MIN' and
536: `MPFR_PREC_MAX'.
537:
538: - Function: void mpfr_clear (mpfr_t X)
539: Free the space occupied by X. Make sure to call this function for
540: all `mpfr_t' variables when you are done with them.
541:
542: Here is an example on how to initialize floating-point variables:
543: {
544: mpfr_t x, y;
545: mpfr_init (x); /* use default precision */
546: mpfr_init2 (y, 256); /* precision _exactly_ 256 bits */
547: ...
548: /* Unless the program is about to exit, do ... */
549: mpfr_clear (x);
550: mpfr_clear (y);
551: }
552:
553: The following two functions are useful for changing the precision
554: during a calculation. A typical use would be for adjusting the
555: precision gradually in iterative algorithms like Newton-Raphson, making
556: the computation precision closely match the actual accurate part of the
557: numbers.
558:
559: - Function: int mpfr_set_prec (mpfr_t X, mp_prec_t PREC)
560: Reset the precision of X to be *exactly* PREC bits. The previous
561: value stored in X is lost. It is equivalent to a call to
562: `mpfr_clear(x)' followed by a call to `mpfr_init2(x, prec)', but
563: more efficient as no allocation is done in case the current
564: allocated space for the mantissa of X is enough. The precision
565: PREC can be any integer between `MPFR_PREC_MIN' and
566: `MPFR_PREC_MAX'. It returns a non-zero value iff the memory
567: allocation failed.
568:
569: In case you want to keep the previous value stored in X, use
570: `mpfr_round_prec' instead.
571:
572: - Function: mp_prec_t mpfr_get_prec (mpfr_t X)
573: Return the precision actually used for assignments of X, i.e. the
574: number of bits used to store its mantissa.
575:
576: - Function: void mpfr_set_prec_raw (mpfr_t X, unsigned long int P)
577: Reset the precision of X to be *exactly* PREC bits. The only
578: difference with `mpfr_set_prec' is that P is assumed to be small
579: enough so that the mantissa fits into the current allocated memory
580: space for X. Otherwise an error will occur.
581:
582:
583: File: mpfr.info, Node: Assigning Floats, Next: Simultaneous Float Init & Assign, Prev: Initializing Floats, Up: Floating-point Functions
584:
585: Assignment Functions
586: ====================
587:
588: These functions assign new values to already initialized floats
589: (*note Initializing Floats::).
590:
591: - Function: int mpfr_set (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
592: - Function: int mpfr_set_ui (mpfr_t ROP, unsigned long int OP,
593: mp_rnd_t RND)
594: - Function: int mpfr_set_si (mpfr_t ROP, long int OP, mp_rnd_t RND
595: - Function: int mpfr_set_d (mpfr_t ROP, double OP, mp_rnd_t RND)
596: - Function: int mpfr_set_z (mpfr_t ROP, mpz_t OP, mp_rnd_t RND)
597: - Function: int mpfr_set_q (mpfr_t ROP, mpq_t OP, mp_rnd_t RND)
598: Set the value of ROP from OP, rounded to the precision of ROP
599: towards the given direction RND. Please note that even a `long
600: int' may have to be rounded, if the destination precision is less
601: than the machine word width. The return value is zero when
602: ROP=OP, positive when ROP>OP, and negative when ROP<OP. For
603: `mpfr_set_d', be careful that the input number OP may not be
604: exactly representable as a double-precision number (this happens
605: for 0.1 for instance), in which case it is first rounded by the C
606: compiler to a double-precision number, and then only to a mpfr
607: floating-point number.
608:
609: - Function: int mpfr_set_str (mpfr_t X, char *S, int BASE, mp_rnd_t
610: RND)
611: Set X to the value of the string S in base BASE (between 2 and
612: 36), rounded in direction RND to the precision of X. The exponent
613: is read in decimal. This function returns -1 if an internal
614: overflow occurred (for instance, because the exponent is too
615: large). Otherwise it returns 0 if the base is valid and if the
616: entire string up to the final '\0' is a valid number in base BASE,
617: and 1 if the input is incorrect.
618:
619: - Function: void mpfr_set_str_raw (mpfr_t X, char *S)
620: Set X to the value of the binary number in string S, which has to
621: be of the form +/-xxxx.xxxxxxEyy. The exponent is read in decimal,
622: but is interpreted as the power of two to be multiplied by the
623: mantissa. The mantissa length of S has to be less or equal to the
624: precision of X, otherwise an error occurs. If S starts with `N',
625: it is interpreted as NaN (Not-a-Number); if it starts with `I'
626: after the sign, it is interpreted as infinity, with the
627: corresponding sign.
628:
629: - Function: int mpfr_set_f (mpfr_t X, mpf_t Y, mp_rnd_t RND)
630: Set X to the GNU MP floating-point number Y, rounded with the RND
631: mode and the precision of X. The returned value is zero when X=Y,
632: positive when X>Y, and negative when X<Y.
633:
634: - Function: void mpfr_set_inf (mpfr_t X, int SIGN)
635: - Function: void mpfr_set_nan (mpfr_t X)
636: Set the variable X to infinity or NaN (Not-a-Number) respectively.
637: In `mpfr_set_inf', X is set to plus infinity iff SIGN is positive.
638:
639: - Function: void mpfr_swap (mpfr_t X, mpfr_t Y)
640: Swap the values X and Y efficiently. Warning: the precisions are
641: exchanged too; in case the precisions are different, `mpfr_swap'
642: is thus not equivalent to three `mpfr_set' calls using a third
643: auxiliary variable.
644:
645:
646: File: mpfr.info, Node: Simultaneous Float Init & Assign, Next: Converting Floats, Prev: Assigning Floats, Up: Floating-point Functions
647:
648: Combined Initialization and Assignment Functions
649: ================================================
650:
651: - Macro: int mpfr_init_set (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
652: - Macro: int mpfr_init_set_ui (mpfr_t ROP, unsigned long int OP,
653: mp_rnd_t RND)
654: - Macro: int mpfr_init_set_si (mpfr_t ROP, signed long int OP,
655: mp_rnd_t RND)
656: - Macro: int mpfr_init_set_d (mpfr_t ROP, double OP, mp_rnd_t RND)
657: - Macro: int mpfr_init_set_f (mpfr_t ROP, mpf_t OP, mp_rnd_t RND)
658: - Macro: int mpfr_init_set_z (mpfr_t ROP, mpz_t OP, mp_rnd_t RND)
659: - Macro: int mpfr_init_set_q (mpfr_t ROP, mpq_t OP, mp_rnd_t RND)
660: Initialize ROP and set its value from OP, rounded to direction RND.
661: The precision of ROP will be taken from the active default
662: precision, as set by `mpfr_set_default_prec'. The return value if
663: zero if ROP=OP, positive if ROP>OP, and negative when ROP<OP.
664:
665: - Function: int mpfr_init_set_str (mpfr_t X, char *S, int BASE,
666: mp_rnd_t RND)
667: Initialize X and set its value from the string S in base BASE,
668: rounded to direction RND. See `mpfr_set_str'.
669:
670:
671: File: mpfr.info, Node: Converting Floats, Next: Float Arithmetic, Prev: Simultaneous Float Init & Assign, Up: Floating-point Functions
672:
673: Conversion Functions
674: ====================
675:
676: - Function: double mpfr_get_d (mpfr_t OP, mp_rnd_t RND)
677: Convert OP to a double, using the rounding mode RND.
678:
679: - Function: double mpfr_get_d1 (mpfr_t OP)
680: Convert OP to a double, using the default MPFR rounding mode (see
681: function `mpfr_set_default_rounding_mode').
682:
683: - Function: mp_exp_t mpfr_get_z_exp (mpz_t Z, mpfr_t OP)
684: Puts the mantissa of OP into Z, and returns the exponent EXP such
685: that OP equals Z multiplied by two exponent EXP.
686:
687: - Function: char * mpfr_get_str (char *STR, mp_exp_t *EXPPTR, int
688: BASE, size_t N_DIGITS, mpfr_t OP, mp_rnd_t RND)
689: Convert OP to a string of digits in base BASE, with rounding in
690: direction RND. The base may vary from 2 to 36. Generate exactly
691: N_DIGITS significant digits.
692:
693: If N_DIGITS is 0, it writes the maximum possible number of digits
694: giving an exact rounding in the given base BASE with the direction
695: RND. In other words, if OP was the exact rounding of a real number
696: in direction RND, then the written value is also an exact rounding
697: in base BASE of that real number with the same precision. An error
698: occurs when one is unable to determine the leading digit, which
699: can happen especially if the precision of OP is small.
700:
701: If STR is a null pointer, space for the mantissa is allocated using
702: the default allocation function, and a pointer to the string is
703: returned. In that case, the user should her/himself free the
704: corresponding memory with `(*_mp_free_func)(s, strlen(s) + 1)'.
705:
706: If STR is not a null pointer, it should point to a block of storage
707: large enough for the mantissa, i.e., N_DIGITS + 2 or more. The
708: extra two bytes are for a possible minus sign, and for the
709: terminating null character.
710:
711: If the input number is a real number, the exponent is written
712: through the pointer EXPPTR (the current minimal exponent for 0).
713:
714: If N_DIGITS is 0, note that the space requirements for STR in this
715: case will be impossible for the user to predetermine. Therefore,
716: one needs to pass a null pointer for the string argument whenever
717: N_DIGITS is 0.
718:
719: The generated string is a fraction, with an implicit radix point
720: immediately to the left of the first digit. For example, the
721: number 3.1416 would be returned as "31416" in the string and 1
722: written at EXPPTR.
723:
724: A pointer to the string is returned, unless there is an error, in
725: which case a null pointer is returned.
726:
727:
728: File: mpfr.info, Node: Float Arithmetic, Next: Float Comparison, Prev: Converting Floats, Up: Floating-point Functions
729:
730: Basic Arithmetic Functions
731: ==========================
732:
733: - Function: int mpfr_add (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, mp_rnd_t
734: RND)
735: - Function: int mpfr_add_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int
736: OP2, mp_rnd_t RND)
737: - Function: int mpfr_add_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2,
738: mp_rnd_t RND)
739: - Function: int mpfr_add_q (mpfr_t ROP, mpfr_t OP1, mpq_t OP2,
740: mp_rnd_t RND)
741: Set ROP to OP1 + OP2 rounded in the direction RND. The return
742: value is zero if ROP is exactly OP1 + OP2, positive if ROP is
743: larger than OP1 + OP2, and negative if ROP is smaller than OP1 +
744: OP2.
745:
746: - Function: int mpfr_sub (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, mp_rnd_t
747: RND)
748: - Function: int mpfr_ui_sub (mpfr_t ROP, unsigned long int OP1, mpfr_t
749: OP2, mp_rnd_t RND)
750: - Function: int mpfr_sub_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int
751: OP2, mp_rnd_t RND)
752: - Function: int mpfr_sub_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2,
753: mp_rnd_t RND)
754: - Function: int mpfr_sub_q (mpfr_t ROP, mpfr_t OP1, mpq_t OP2,
755: mp_rnd_t RND)
756: Set ROP to OP1 - OP2 rounded in the direction RND. The return
757: value is zero if ROP is exactly OP1 - OP2, positive if ROP is
758: larger than OP1 - OP2, and negative if ROP is smaller than OP1 -
759: OP2.
760:
761: - Function: int mpfr_mul (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, mp_rnd_t
762: RND)
763: - Function: int mpfr_mul_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int
764: OP2, mp_rnd_t RND)
765: - Function: int mpfr_mul_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2,
766: mp_rnd_t RND)
767: - Function: int mpfr_mul_q (mpfr_t ROP, mpfr_t OP1, mpq_t OP2,
768: mp_rnd_t RND)
769: Set ROP to OP1 times OP2 rounded in the direction RND. Return 0
770: if the result is exact, a positive value if ROP>OP1*OP2, a
771: negative value otherwise.
772:
773: - Function: int mpfr_div (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, mp_rnd_t
774: RND)
775: - Function: int mpfr_ui_div (mpfr_t ROP, unsigned long int OP1, mpfr_t
776: OP2, mp_rnd_t RND)
777: - Function: int mpfr_div_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int
778: OP2, mp_rnd_t RND)
779: - Function: int mpfr_div_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2,
780: mp_rnd_t RND)
781: - Function: int mpfr_div_q (mpfr_t ROP, mpfr_t OP1, mpq_t OP2,
782: mp_rnd_t RND)
783: Set ROP to OP1/OP2 rounded in the direction RND. These functions
784: return 0 if the division is exact, a positive value when ROP is
785: larger than OP1 divided by OP2, and a negative value otherwise.
786:
787: - Function: int mpfr_sqrt (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
788: - Function: int mpfr_sqrt_ui (mpfr_t ROP, unsigned long int OP,
789: mp_rnd_t RND)
790: Set ROP to the square root of OP rounded in the direction RND.
791: Set ROP to NaN if OP is negative. Return 0 if the operation is
792: exact, a non-zero value otherwise.
793:
794: - Function: int mpfr_pow_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int
795: OP2, mp_rnd_t RND)
796: - Function: int mpfr_ui_pow_ui (mpfr_t ROP, unsigned long int OP1,
797: unsigned long int OP2, mp_rnd_t RND)
798: Set ROP to OP1 raised to OP2. The computation is done by binary
799: exponentiation. Return 0 if the result is exact, a non-zero value
800: otherwise (but the sign of the return value has no meaning).
801:
802: - Function: int mpfr_ui_pow (mpfr_t ROP, unsigned long int OP1, mpfr_t
803: OP2, mp_rnd_t RND)
804: Set ROP to OP1 raised to OP2, rounded to the direction RND with
805: the precision of ROP. Return zero iff the result is exact, a
806: positive value when the result is greater than OP1 to the power
807: OP2, and a negative value when it is smaller.
808:
809: - Function: int mpfr_pow_si (mpfr_t ROP, mpfr_t OP1, long int OP2,
810: mp_rnd_t RND)
811: Set ROP to OP1 raised to the power OP2, rounded to the direction
812: RND with the precision of ROP. Return zero iff the result is
813: exact.
814:
815: - Function: int mpfr_pow (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, mp_rnd_t
816: RND)
817: Set ROP to OP1 raised to the power OP2, rounded to the direction
818: RND with the precision of ROP. If OP1 is negative then ROP is set
819: to NaN, even if OP2 is an integer. Return zero iff the result is
820: exact.
821:
822: - Function: int mpfr_neg (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
823: Set ROP to -OP rounded in the direction RND. Just changes the sign
824: if ROP and OP are the same variable.
825:
826: - Function: int mpfr_abs (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
827: Set ROP to the absolute value of OP, rounded in the direction RND.
828: Return 0 if the result is exact, a positive value if ROP is larger
829: than the absolute value of OP, and a negative value otherwise.
830:
831: - Function: int mpfr_mul_2exp (mpfr_t ROP, mpfr_t OP1, unsigned long
832: int OP2, mp_rnd_t RND)
833: - Function: int mpfr_mul_2ui (mpfr_t ROP, mpfr_t OP1, unsigned long
834: int OP2, mp_rnd_t RND)
835: - Function: int mpfr_mul_2si (mpfr_t ROP, mpfr_t OP1, long int OP2,
836: mp_rnd_t RND)
837: Set ROP to OP1 times 2 raised to OP2 rounded to the direction RND.
838: Just increases the exponent by OP2 when ROP and OP1 are identical.
839: Return zero when ROP=OP1, a positive value when ROP>OP1, and a
840: negative value when ROP<OP1. Note: The `mpfr_mul_2exp' function
841: is defined for compatibility reasons; you should use
842: `mpfr_mul_2ui' (or `mpfr_mul_2si') instead.
843:
844: - Function: int mpfr_div_2exp (mpfr_t ROP, mpfr_t OP1, unsigned long
845: int OP2, mp_rnd_t RND)
846: - Function: int mpfr_div_2ui (mpfr_t ROP, mpfr_t OP1, unsigned long
847: int OP2, mp_rnd_t RND)
848: - Function: int mpfr_div_2si (mpfr_t ROP, mpfr_t OP1, long int OP2,
849: mp_rnd_t RND)
850: Set ROP to OP1 divided by 2 raised to OP2 rounded to the direction
851: RND. Just decreases the exponent by OP2 when ROP and OP1 are
852: identical. Return zero when ROP=OP1, a positive value when
853: ROP>OP1, and a negative value when ROP<OP1. Note: The
854: `mpfr_div_2exp' function is defined for compatibility reasons; you
855: should use `mpfr_div_2ui' (or `mpfr_div_2si') instead.
856:
857:
858: File: mpfr.info, Node: Float Comparison, Next: I/O of Floats, Prev: Float Arithmetic, Up: Floating-point Functions
859:
860: Comparison Functions
861: ====================
862:
863: - Function: int mpfr_cmp (mpfr_t OP1, mpfr_t OP2)
864: - Function: int mpfr_cmp_ui (mpfr_t OP1, unsigned long int OP2)
865: - Function: int mpfr_cmp_si (mpfr_t OP1, signed long int OP2)
866: Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
867: if OP1 = OP2, and a negative value if OP1 < OP2. Both OP1 and OP2
868: are considered to their full own precision, which may differ. In
869: case OP1 and OP2 are of same sign but different, the absolute
870: value returned is one plus the absolute difference of their
871: exponents. It is not allowed that one of the operands is NaN
872: (Not-a-Number).
873:
874: - Function: int mpfr_cmp_ui_2exp (mpfr_t OP1, unsigned long int OP2,
875: int E)
876: - Function: int mpfr_cmp_si_2exp (mpfr_t OP1, long int OP2, int E)
877: Compare OP1 and OP2 multiplied by two to the power E.
878:
879: - Function: int mpfr_eq (mpfr_t OP1, mpfr_t OP2, unsigned long int op3)
880: Return non-zero if the first OP3 bits of OP1 and OP2 are equal,
881: zero otherwise. I.e., tests if OP1 and OP2 are approximately
882: equal.
883:
884: - Function: int mpfr_nan_p (mpfr_t OP)
885: Return non-zero if OP is Not-a-Number (NaN), zero otherwise.
886:
887: - Function: int mpfr_inf_p (mpfr_t OP)
888: Return non-zero if OP is plus or minus infinity, zero otherwise.
889:
890: - Function: int mpfr_number_p (mpfr_t OP)
891: Return non-zero if OP is an ordinary number, i.e. neither
892: Not-a-Number nor plus or minus infinity.
893:
894: - Function: void mpfr_reldiff (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2,
895: mp_rnd_t RND)
896: Compute the relative difference between OP1 and OP2 and store the
897: result in ROP. This function does not guarantee the exact
898: rounding on the relative difference; it just computes
899: abs(OP1-OP2)/OP1, using the rounding mode RND for all operations.
900:
901: - Function: int mpfr_sgn (mpfr_t OP)
902: Return a positive value if OP > 0, zero if OP = 0, and a negative
903: value if OP < 0. Its result is not specified when OP is NaN
904: (Not-a-Number).
905:
906: Special Functions
907: =================
908:
909: - Function: int mpfr_log (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
910: Set ROP to the natural logarithm of OP, rounded to the direction
911: RND with the precision of ROP. Return zero when the result is
912: exact (this occurs in fact only when OP is 0, 1, or +infinity) and
913: a non-zero value otherwise (except for rounding to nearest, the
914: sign of the return value is that of ROP-log(OP).
915:
916: - Function: int mpfr_exp (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
917: Set ROP to the exponential of OP, rounded to the direction RND
918: with the precision of ROP. Return zero when the result is exact
919: (this occurs in fact only when OP is -infinity, 0, or +infinity),
920: a positive value when the result is greater than the exponential
921: of OP, and a negative value when it is smaller.
922:
923: - Function: int mpfr_exp2 (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
924: Set ROP to 2 power of OP, rounded to the direction RND with the
925: precision of ROP. Return zero iff the result is exact (this
926: occurs in fact only when OP is -infinity, 0, or +infinity), a
927: positive value when the result is greater than the exponential of
928: OP, and a negative value when it is smaller.
929:
930: - Function: int mpfr_cos (mpfr_t COP, mpfr_t OP, mp_rnd_t RND)
931: - Function: int mpfr_sin (mpfr_t SOP, mpfr_t OP, mp_rnd_t RND)
932: - Function: int mpfr_tan (mpfr_t TOP, mpfr_t OP, mp_rnd_t RND)
933: Set COP to the cosine of OP, SOP to the sine of OP, TOP to the
934: tangent of OP, rounded to the direction RND with the precision of
935: ROP. Return 0 iff the result is exact (this occurs in fact only
936: when OP is 0 i.e. the sine is 0, the cosine is 1, and the tangent
937: is 0).
938:
939: - Function: int mpfr_sin_cos (mpfr_t SOP, mpfr_t COP, mpfr_t OP,
940: mp_rnd_t RND)
941: Set simultaneously SOP to the sine of OP and
942: COP to the cosine of OP, rounded to the direction RND with their
943: corresponding precisions. Return 0 iff both results are exact.
944:
945: - Function: int mpfr_acos (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
946: - Function: int mpfr_asin (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
947: - Function: int mpfr_atan (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
948: Set ROP to the arc-cosine, arc-sine or arc-tangent of OP, rounded
949: to the direction RND with the precision of ROP. Return 0 iff the
950: result is exact.
951:
952: - Function: int mpfr_cosh (mpfr_t COP, mpfr_t OP, mp_rnd_t RND)
953: - Function: int mpfr_sinh (mpfr_t SOP, mpfr_t OP, mp_rnd_t RND)
954: - Function: int mpfr_tanh (mpfr_t TOP, mpfr_t OP, mp_rnd_t RND)
955: Set COP to the hyperbolic cosine of OP, SOP to the hyperbolic
956: sine of OP, TOP to the hyperbolic tangent of OP, rounded to
957: the direction RND with the precision of ROP. Return 0 iff the
958: result is exact (this occurs in fact only when OP is 0 i.e. the
959: result is 1).
960:
961: - Function: int mpfr_acosh (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
962: - Function: int mpfr_asinh (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
963: - Function: int mpfr_atanh (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
964: Set ROP to the inverse hyperbolic cosine, sine or tangent of OP,
965: rounded to the direction RND with the precision of ROP. Return 0
966: iff the result is exact.
967:
968: - Function: int mpfr_fac_ui (mpfr_t ROP, unsigned long int OP,
969: mp_rnd_t RND)
970: Set ROP to the factorial of the unsigned long int OP, rounded to
971: the direction RND with the precision of ROP. Return 0 iff the
972: result is exact.
973:
974: - Function: int mpfr_log1p (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
975: Set ROP to the logarithm of one plus OP, rounded to the direction
976: RND with the precision of ROP. Return 0 iff the result is exact
977: (this occurs in fact only when OP is 0 i.e. the result is 0).
978:
979: - Function: int mpfr_expm1 (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
980: Set ROP to the exponential of OP minus one, rounded to the
981: direction RND with the precision of ROP. Return 0 iff the result
982: is exact (this occurs in fact only when OP is 0 i.e. the result is
983: 0).
984:
985: - Function: int mpfr_log2 (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
986: - Function: int mpfr_log10 (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
987: Set ROP to the log[t] (t=2 or 10)(log x / log t) of OP, rounded to
988: the direction RND with the precision of ROP. Return 0 iff the
989: result is exact (this occurs in fact only when OP is 1 i.e. the
990: result is 0).
991:
992: - Function: int mpfr_fma (mpfr_t ROP, mpfr_t OPX,mpfr_t OPY,mpfr_t
993: OPZ, mp_rnd_t RND)
994: Set ROP to OPX * OPY + OPZ, rounded to the direction RND with the
995: precision of ROP. Return 0 iff the result is exact, a positive
996: value if ROP is larger than OPX * OPY + OPZ, and a negative value
997: otherwise.
998:
999: - Function: void mpfr_agm (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2,
1000: mp_rnd_t RND)
1001: Set ROP to the arithmetic-geometric mean of OP1 and OP2, rounded
1002: to the direction RND with the precision of ROP.
1003:
1004: - Function: void mpfr_const_log2 (mpfr_t ROP, mp_rnd_t RND)
1005: Set ROP to the logarithm of 2 rounded to the direction RND with
1006: the precision of ROP. This function stores the computed value to
1007: avoid another calculation if a lower or equal precision is
1008: requested.
1009:
1010: - Function: void mpfr_const_pi (mpfr_t ROP, mp_rnd_t RND)
1011: Set ROP to the value of Pi rounded to the direction RND with the
1012: precision of ROP. This function uses the Borwein, Borwein, Plouffe
1013: formula which directly gives the expansion of Pi in base 16.
1014:
1015: - Function: void mpfr_const_euler (mpfr_t ROP, mp_rnd_t RND)
1016: Set ROP to the value of Euler's constant 0.577... rounded to the
1017: direction RND with the precision of ROP.
1018:
1019:
1020: File: mpfr.info, Node: I/O of Floats, Next: Miscellaneous Float Functions, Prev: Float Comparison, Up: Floating-point Functions
1021:
1022: Input and Output Functions
1023: ==========================
1024:
1025: Functions that perform input from a standard input/output stream,
1026: and functions that output to a standard input/output stream. Passing a
1027: null pointer for a STREAM argument to any of these functions will make
1028: them read from `stdin' and write to `stdout', respectively.
1029:
1030: When using any of these functions, it is a good idea to include
1031: `stdio.h' before `mpfr.h', since that will allow `mpfr.h' to define
1032: prototypes for these functions.
1033:
1034: - Function: size_t mpfr_out_str (FILE *STREAM, int BASE, size_t
1035: N_DIGITS, mpfr_t OP, mp_rnd_t RND)
1036: Output OP on stdio stream STREAM, as a string of digits in base
1037: BASE, rounded to direction RND. The base may vary from 2 to 36.
1038: Print at most N_DIGITS significant digits, or if N_DIGITS is 0,
1039: the maximum number of digits accurately representable by OP.
1040:
1041: In addition to the significant digits, a decimal point at the
1042: right of the first digit and a trailing exponent, in the form
1043: `eNNN', are printed. If BASE is greater than 10, `@' will be used
1044: instead of `e' as exponent delimiter.
1045:
1046: Return the number of bytes written, or if an error occurred,
1047: return 0.
1048:
1049: - Function: size_t mpfr_inp_str (mpfr_t ROP, FILE *STREAM, int BASE,
1050: mp_rnd_t RND)
1051: Input a string in base BASE from stdio stream STREAM, rounded in
1052: direction RND, and put the read float in ROP. The string is of
1053: the form `M@N' or, if the base is 10 or less, alternatively `MeN'
1054: or `MEN'. `M' is the mantissa and `N' is the exponent. The
1055: mantissa is always in the specified base. The exponent is in
1056: decimal.
1057:
1058: The argument BASE may be in the range 2 to 36.
1059:
1060: Unlike the corresponding `mpz' function, the base will not be
1061: determined from the leading characters of the string if BASE is 0.
1062: This is so that numbers like `0.23' are not interpreted as octal.
1063:
1064: Return the number of bytes read, or if an error occurred, return 0.
1065:
1066: - Function: void mpfr_print_binary (mpfr_t FLOAT)
1067: Output FLOAT on stdout in raw binary format (the exponent is in
1068: decimal, yet). The last bits from the least significant limb
1069: which do not belong to the mantissa are printed between square
1070: brackets; they should always be zero.
1071:
1072:
1073: File: mpfr.info, Node: Miscellaneous Float Functions, Prev: I/O of Floats, Up: Floating-point Functions
1074:
1075: Miscellaneous Functions
1076: =======================
1077:
1078: - Function: int mpfr_rint (mpfr_t ROP, mpfr_t OP, mp_rnd_t RND)
1079: - Function: int mpfr_ceil (mpfr_t ROP, mpfr_t OP)
1080: - Function: int mpfr_floor (mpfr_t ROP, mpfr_t OP)
1081: - Function: int mpfr_round (mpfr_t ROP, mpfr_t OP)
1082: - Function: int mpfr_trunc (mpfr_t ROP, mpfr_t OP)
1083: Set ROP to OP rounded to an integer. `mpfr_ceil' rounds to the
1084: next higher representable integer, `mpfr_floor' to the next lower,
1085: `mpfr_round' to the nearest representable integer, rounding
1086: halfway cases away from zero, and `mpfr_trunc' to the
1087: representable integer towards zero. `mpfr_rint' behaves like one
1088: of these four functions, depending on the rounding mode. The
1089: returned value is zero when the result is exact, positive when it
1090: is greater than the original value of OP, and negative when it is
1091: smaller. More precisely, the returned value is 0 when OP is an
1092: integer representable in ROP, 1 or -1 when OP is an integer that
1093: is not representable in ROP, 2 or -2 when OP is not an integer.
1094:
1095: - Function: void mpfr_urandomb (mpfr_t ROP, gmp_randstate_t STATE)
1096: Generate a uniformly distributed random float in the interval 0 <=
1097: X < 1.
1098:
1099: - Function: void mpfr_random (mpfr_t ROP)
1100: Generate a uniformly distributed random float in the interval 0 <=
1101: X < 1.
1102:
1103: - Function: void mpfr_random2 (mpfr_t ROP, mp_size_t MAX_SIZE,
1104: mp_exp_t MAX_EXP)
1105: Generate a random float of at most MAX_SIZE limbs, with long
1106: strings of zeros and ones in the binary representation. The
1107: exponent of the number is in the interval -EXP to EXP. This
1108: function is useful for testing functions and algorithms, since
1109: this kind of random numbers have proven to be more likely to
1110: trigger corner-case bugs. Negative random numbers are generated
1111: when MAX_SIZE is negative.
1112:
1113: Internals
1114: =========
1115:
1116: These types and functions were mainly designed for the
1117: implementation of `mpfr', but may be useful for users too. However no
1118: upward compatibility is guaranteed. You need to include `mpfr-impl.h'
1119: to use them.
1120:
1121: The `mpfr_t' type consists of four fields. The `_mpfr_prec' field
1122: is used to store the precision of the variable (in bits); this is not
1123: less than 2.
1124:
1125: The `_mpfr_size' field is used to store the number of allocated
1126: limbs, with the high bits reserved to store the sign (bit 31), the NaN
1127: flag (bit 30), and the Infinity flag (bit 29); thus bits 0 to 28 remain
1128: for the number of allocated limbs, with a maximal value of 536870911.
1129: A NaN is indicated by the NaN flag set, and no other fields are
1130: relevant. An Infinity is indicated by the NaN flag clear and the Inf
1131: flag set; the sign bit of an Infinity indicates the sign, the limb data
1132: and the exponent are not relevant.
1133:
1134: The `_mpfr_exp' field stores the exponent. An exponent of 0 means a
1135: radix point just above the most significant limb. Non-zero values are
1136: a multiplier 2^n relative to that point.
1137:
1138: Finally, the `_mpfr_d' is a pointer to the limbs, least significant
1139: limbs stored first. The number zero is represented with its most
1140: significant limb set to zero, i.e. `_mpfr_d[n-1]' where
1141: n=ceil(`_mpfr_prec'/`BITS_PER_MP_LIMB'). The number of limbs in use is
1142: controlled by `_mpfr_prec', namely
1143: ceil(`_mpfr_prec'/`BITS_PER_MP_LIMB'). Zero is represented by the most
1144: significant limb being zero, other limb data and the exponent are not
1145: relevant ("not relevant" implies that the corresponding objects may
1146: contain invalid values, thus should not be evaluated even if they are
1147: not taken into account). Non-zero values always have the most
1148: significant bit of the most significant limb set to 1. When the
1149: precision is not a whole number of limbs, the excess bits at the low
1150: end of the data are zero. When the precision has been lowered by
1151: `mpfr_set_prec', the space allocated at `_mpfr_d' remains as given by
1152: `_mpfr_size', but `_mpfr_prec' indicates how much of that space is
1153: actually used.
1154:
1155: - Function: int mpfr_add_one_ulp (mpfr_t X, mp_rnd_t RND)
1156: Add one unit in last place (ulp) to X if X is finite and positive,
1157: subtract one ulp if X is finite and negative; otherwise, X is not
1158: changed. The return value is zero unless an overflow occurs, in
1159: which case the `mpfr_add_one_ulp' function behaves like a
1160: conventional addition.
1161:
1162: - Function: int mpfr_sub_one_ulp (mpfr_t X, mp_rnd_t RND)
1163: Subtract one ulp to X if X is finite and positive, add one ulp if
1164: X is finite and negative; otherwise, X is not changed. The return
1165: value is zero unless an underflow occurs, in which case the
1166: `mpfr_sub_one_ulp' function behaves like a conventional
1167: subtraction.
1168:
1169: - Function: int mpfr_can_round (mpfr_t B, mp_exp_t ERR, mp_rnd_t RND1,
1170: mp_rnd_t RND2, mp_prec_t PREC)
1171: Assuming B is an approximation of an unknown number X in direction
1172: RND1 with error at most two to the power E(b)-ERR where E(b) is
1173: the exponent of B, returns 1 if one is able to round exactly X to
1174: precision PREC with direction RND2, and 0 otherwise. This
1175: function *does not modify* its arguments.
1176:
1177:
1178: File: mpfr.info, Node: Contributors, Next: References, Prev: Floating-point Functions, Up: Top
1179:
1180: Contributors
1181: ************
1182:
1183: The main developers consist of Guillaume Hanrot, Vincent Lefèvre and
1184: Paul Zimmermann.
1185:
1186: We would like to thank Jean-Michel Muller and Joris van der Hoeven
1187: for very fruitful discussions at the beginning of that project,
1188: Torbjorn Granlund and Kevin Ryde for their help about design issues and
1189: their suggestions for an easy integration into GNU MP, and Nathalie
1190: Revol for her careful reading of this documentation.
1191:
1192: Sylvie Boldo from ENS-Lyon, France, contributed the functions
1193: `mpfr_agm' and `mpfr_log'. Emmanuel Jeandel, from ENS-Lyon too,
1194: contributed the generic hypergeometric code in `generic.c', as well as
1195: the `mpfr_exp3', a first implementation of the sine and cosine, and
1196: improved versions of `mpfr_const_log2' and `mpfr_const_pi'. Mathieu
1197: Dutour contributed the functions `mpfr_atan' and `mpfr_asin', David
1198: Daney contributed the hyperbolic and inverse hyperbolic functions, the
1199: base-2 exponential, and the factorial function. Fabrice Rouillier
1200: contributed the original version of `mul_ui.c', the `gmp_op.c' file,
1201: and helped to the Windows porting.
1202:
1203:
1204: File: mpfr.info, Node: References, Next: Concept Index, Prev: Contributors, Up: Top
1205:
1206: References
1207: **********
1208:
1209: * Torbjorn Granlund, "GNU MP: The GNU Multiple Precision Arithmetic
1210: Library", version 4.0.1, 2001.
1211:
1212: * IEEE standard for binary floating-point arithmetic, Technical
1213: Report ANSI-IEEE Standard 754-1985, New York, 1985. Approved
1214: March 21, 1985: IEEE Standards Board; approved July 26, 1985:
1215: American National Standards Institute, 18 pages.
1216:
1217: * Donald E. Knuth, "The Art of Computer Programming", vol 2,
1218: "Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981.
1219:
1220:
1221:
1222: File: mpfr.info, Node: Concept Index, Next: Function Index, Prev: References, Up: Top
1223:
1224: Concept Index
1225: *************
1226:
1227: * Menu:
1228:
1229: * Arithmetic functions: Float Arithmetic.
1230: * Comparison functions: Float Comparison.
1231: * Conditions for copying MPFR: Copying.
1232: * Conversion functions: Converting Floats.
1233: * Copying conditions: Copying.
1234: * Float arithmetic functions: Float Arithmetic.
1235: * Float assignment functions: Assigning Floats.
1236: * Float comparisons functions: Float Comparison.
1237: * Float functions: Floating-point Functions.
1238: * Float input and output functions: I/O of Floats.
1239: * Floating-point functions: Floating-point Functions.
1240: * Floating-point number: MPFR Basics.
1241: * I/O functions: I/O of Floats.
1242: * Initialization and assignment functions: Simultaneous Float Init & Assign.
1243: * Input functions: I/O of Floats.
1244: * Installation: Installing MPFR.
1245: * Limb: MPFR Basics.
1246: * Miscellaneous float functions: Miscellaneous Float Functions.
1247: * mpfr.h: MPFR Basics.
1248: * Output functions: I/O of Floats.
1249: * Precision: MPFR Basics.
1250: * Reporting bugs: Reporting Bugs.
1251: * Rounding Mode: MPFR Basics.
1252: * Rounding modes: Rounding Modes.
1253: * Special functions: Float Comparison.
1254: * User-defined precision: Floating-point Functions.
1255:
1256:
1257: File: mpfr.info, Node: Function Index, Prev: Concept Index, Up: Top
1258:
1259: Function and Type Index
1260: ***********************
1261:
1262: * Menu:
1263:
1264: * mp_prec_t: MPFR Basics.
1265: * mp_rnd_t: MPFR Basics.
1266: * mpfr_abs: Float Arithmetic.
1267: * mpfr_acos: Float Comparison.
1268: * mpfr_acosh: Float Comparison.
1269: * mpfr_add: Float Arithmetic.
1270: * mpfr_add_one_ulp: Miscellaneous Float Functions.
1271: * mpfr_add_q: Float Arithmetic.
1272: * mpfr_add_ui: Float Arithmetic.
1273: * mpfr_add_z: Float Arithmetic.
1274: * mpfr_agm: Float Comparison.
1275: * mpfr_asin: Float Comparison.
1276: * mpfr_asinh: Float Comparison.
1277: * mpfr_atan: Float Comparison.
1278: * mpfr_atanh: Float Comparison.
1279: * mpfr_can_round: Miscellaneous Float Functions.
1280: * mpfr_ceil: Miscellaneous Float Functions.
1281: * mpfr_check_range: Exceptions.
1282: * mpfr_clear: Initializing Floats.
1283: * mpfr_clear_flags: Exceptions.
1284: * mpfr_clear_inexflag: Exceptions.
1285: * mpfr_clear_nanflag: Exceptions.
1286: * mpfr_clear_overflow: Exceptions.
1287: * mpfr_clear_underflow: Exceptions.
1288: * mpfr_cmp: Float Comparison.
1289: * mpfr_cmp_si: Float Comparison.
1290: * mpfr_cmp_si_2exp: Float Comparison.
1291: * mpfr_cmp_ui: Float Comparison.
1292: * mpfr_cmp_ui_2exp: Float Comparison.
1293: * mpfr_const_euler: Float Comparison.
1294: * mpfr_const_log2: Float Comparison.
1295: * mpfr_const_pi: Float Comparison.
1296: * mpfr_cos: Float Comparison.
1297: * mpfr_cosh: Float Comparison.
1298: * mpfr_div: Float Arithmetic.
1299: * mpfr_div_2exp: Float Arithmetic.
1300: * mpfr_div_2si: Float Arithmetic.
1301: * mpfr_div_2ui: Float Arithmetic.
1302: * mpfr_div_q: Float Arithmetic.
1303: * mpfr_div_ui: Float Arithmetic.
1304: * mpfr_div_z: Float Arithmetic.
1305: * mpfr_eq: Float Comparison.
1306: * mpfr_exp: Float Comparison.
1307: * mpfr_exp2: Float Comparison.
1308: * mpfr_expm1: Float Comparison.
1309: * mpfr_fac_ui: Float Comparison.
1310: * mpfr_floor: Miscellaneous Float Functions.
1311: * mpfr_fma: Float Comparison.
1312: * mpfr_get_d: Converting Floats.
1313: * mpfr_get_d1: Converting Floats.
1314: * mpfr_get_default_prec: Initializing Floats.
1315: * mpfr_get_emax: Exceptions.
1316: * mpfr_get_emin: Exceptions.
1317: * mpfr_get_prec: Initializing Floats.
1318: * mpfr_get_str: Converting Floats.
1319: * mpfr_get_z_exp: Converting Floats.
1320: * mpfr_inexflag_p: Exceptions.
1321: * mpfr_inf_p: Float Comparison.
1322: * mpfr_init: Initializing Floats.
1323: * mpfr_init2: Initializing Floats.
1324: * mpfr_init_set: Simultaneous Float Init & Assign.
1325: * mpfr_init_set_d: Simultaneous Float Init & Assign.
1326: * mpfr_init_set_f: Simultaneous Float Init & Assign.
1327: * mpfr_init_set_q: Simultaneous Float Init & Assign.
1328: * mpfr_init_set_si: Simultaneous Float Init & Assign.
1329: * mpfr_init_set_str: Simultaneous Float Init & Assign.
1330: * mpfr_init_set_ui: Simultaneous Float Init & Assign.
1331: * mpfr_init_set_z: Simultaneous Float Init & Assign.
1332: * mpfr_inp_str: I/O of Floats.
1333: * mpfr_log: Float Comparison.
1334: * mpfr_log10: Float Comparison.
1335: * mpfr_log1p: Float Comparison.
1336: * mpfr_log2: Float Comparison.
1337: * mpfr_mul: Float Arithmetic.
1338: * mpfr_mul_2exp: Float Arithmetic.
1339: * mpfr_mul_2si: Float Arithmetic.
1340: * mpfr_mul_2ui: Float Arithmetic.
1341: * mpfr_mul_q: Float Arithmetic.
1342: * mpfr_mul_ui: Float Arithmetic.
1343: * mpfr_mul_z: Float Arithmetic.
1344: * mpfr_nan_p: Float Comparison.
1345: * mpfr_nanflag_p: Exceptions.
1346: * mpfr_neg: Float Arithmetic.
1347: * mpfr_number_p: Float Comparison.
1348: * mpfr_out_str: I/O of Floats.
1349: * mpfr_overflow_p: Exceptions.
1350: * mpfr_pow: Float Arithmetic.
1351: * mpfr_pow_si: Float Arithmetic.
1352: * mpfr_pow_ui: Float Arithmetic.
1353: * mpfr_print_binary: I/O of Floats.
1354: * mpfr_print_rnd_mode: Rounding Modes.
1355: * mpfr_random: Miscellaneous Float Functions.
1356: * mpfr_random2: Miscellaneous Float Functions.
1357: * mpfr_reldiff: Float Comparison.
1358: * mpfr_rint: Miscellaneous Float Functions.
1359: * mpfr_round: Miscellaneous Float Functions.
1360: * mpfr_round_prec: Rounding Modes.
1361: * mpfr_set: Assigning Floats.
1362: * mpfr_set_d: Assigning Floats.
1363: * mpfr_set_default_prec: Initializing Floats.
1364: * mpfr_set_default_rounding_mode: Rounding Modes.
1365: * mpfr_set_emax: Exceptions.
1366: * mpfr_set_emin: Exceptions.
1367: * mpfr_set_f: Assigning Floats.
1368: * mpfr_set_inf: Assigning Floats.
1369: * mpfr_set_machine_rnd_mode: Rounding Modes.
1370: * mpfr_set_nan: Assigning Floats.
1371: * mpfr_set_prec: Initializing Floats.
1372: * mpfr_set_prec_raw: Initializing Floats.
1373: * mpfr_set_q: Assigning Floats.
1374: * mpfr_set_si: Assigning Floats.
1375: * mpfr_set_str: Assigning Floats.
1376: * mpfr_set_str_raw: Assigning Floats.
1377: * mpfr_set_ui: Assigning Floats.
1378: * mpfr_set_z: Assigning Floats.
1379: * mpfr_sgn: Float Comparison.
1380: * mpfr_sin: Float Comparison.
1381: * mpfr_sin_cos: Float Comparison.
1382: * mpfr_sinh: Float Comparison.
1383: * mpfr_sqrt: Float Arithmetic.
1384: * mpfr_sqrt_ui: Float Arithmetic.
1385: * mpfr_sub: Float Arithmetic.
1386: * mpfr_sub_one_ulp: Miscellaneous Float Functions.
1387: * mpfr_sub_q: Float Arithmetic.
1388: * mpfr_sub_ui: Float Arithmetic.
1389: * mpfr_sub_z: Float Arithmetic.
1390: * mpfr_swap: Assigning Floats.
1391: * mpfr_t: MPFR Basics.
1392: * mpfr_tan: Float Comparison.
1393: * mpfr_tanh: Float Comparison.
1394: * mpfr_trunc: Miscellaneous Float Functions.
1395: * mpfr_ui_div: Float Arithmetic.
1396: * mpfr_ui_pow: Float Arithmetic.
1397: * mpfr_ui_pow_ui: Float Arithmetic.
1398: * mpfr_ui_sub: Float Arithmetic.
1399: * mpfr_underflow_p: Exceptions.
1400: * mpfr_urandomb: Miscellaneous Float Functions.
1401:
1402:
1403:
1404: Tag Table:
1405: Node: Top1010
1406: Node: Copying1677
1407: Node: Introduction to MPFR3397
1408: Node: Installing MPFR5133
1409: Node: Reporting Bugs7665
1410: Node: MPFR Basics9195
1411: Node: Floating-point Functions13276
1412: Node: Rounding Modes15114
1413: Node: Exceptions18227
1414: Node: Initializing Floats20496
1415: Node: Assigning Floats24168
1416: Node: Simultaneous Float Init & Assign27386
1417: Node: Converting Floats28627
1418: Node: Float Arithmetic31301
1419: Node: Float Comparison37456
1420: Node: I/O of Floats45234
1421: Node: Miscellaneous Float Functions47671
1422: Node: Contributors52903
1423: Node: References54098
1424: Node: Concept Index54714
1425: Node: Function Index56376
1426:
1427: End Tag Table
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to mpfr.info CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gmp / mpfr