diff options
| author | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2016-03-05 23:54:57 +0900 |
|---|---|---|
| committer | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2016-03-05 23:56:36 +0900 |
| commit | 19d034ed935aa53b95537f0b0d39ca7fd78da8ce (patch) | |
| tree | b8f73e91728b9316ac29b3c2ff329ee62682f060 | |
| parent | e5d87d25ead2a930d2e9338bcd7e172b198185ce (diff) | |
| download | gcc-tarball-19d034ed935aa53b95537f0b0d39ca7fd78da8ce.tar.gz | |
Adding missing info filesbaserock/tristan/wip/aboriginal
Not having this causes the build to attempt to build the info
files, but we dont have texinfo while building gcc.
| -rw-r--r-- | gmp/doc/gmp.info | 177 | ||||
| -rw-r--r-- | mpc/doc/mpc.info | 1799 | ||||
| -rw-r--r-- | mpfr/doc/mpfr.info | 4245 |
3 files changed, 6221 insertions, 0 deletions
diff --git a/gmp/doc/gmp.info b/gmp/doc/gmp.info new file mode 100644 index 0000000000..79a544546f --- /dev/null +++ b/gmp/doc/gmp.info @@ -0,0 +1,177 @@ +This is ../../gmp/doc/gmp.info, produced by makeinfo version 4.8 from +../../gmp/doc/gmp.texi. + + This manual describes how to install and use the GNU multiple +precision arithmetic library, version 4.3.2. + + Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, +2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software +Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this +document under the terms of the GNU Free Documentation License, Version +1.3 or any later version published by the Free Software Foundation; +with no Invariant Sections, with the Front-Cover Texts being "A GNU +Manual", and with the Back-Cover Texts being "You have freedom to copy +and modify this GNU Manual, like GNU software". A copy of the license +is included in *Note GNU Free Documentation License::. + +INFO-DIR-SECTION GNU libraries +START-INFO-DIR-ENTRY +* gmp: (gmp). GNU Multiple Precision Arithmetic Library. +END-INFO-DIR-ENTRY + + +Indirect: +gmp.info-1: 975 +gmp.info-2: 299474 + +Tag Table: +(Indirect) +Node: Top975 +Node: Copying3199 +Node: Introduction to GMP5050 +Node: Installing GMP7761 +Node: Build Options8493 +Node: ABI and ISA24561 +Node: Notes for Package Builds34239 +Node: Notes for Particular Systems37326 +Node: Known Build Problems44085 +Node: Performance optimization47619 +Node: GMP Basics48753 +Node: Headers and Libraries49401 +Node: Nomenclature and Types50825 +Node: Function Classes52533 +Node: Variable Conventions54226 +Node: Parameter Conventions55835 +Node: Memory Management57891 +Node: Reentrancy59019 +Node: Useful Macros and Constants60892 +Node: Compatibility with older versions61890 +Node: Demonstration Programs62851 +Node: Efficiency64716 +Node: Debugging72340 +Node: Profiling78898 +Node: Autoconf82889 +Node: Emacs84668 +Node: Reporting Bugs85274 +Node: Integer Functions87817 +Node: Initializing Integers88593 +Node: Assigning Integers90478 +Node: Simultaneous Integer Init & Assign92065 +Node: Converting Integers93690 +Node: Integer Arithmetic96612 +Node: Integer Division98214 +Node: Integer Exponentiation104642 +Node: Integer Roots105503 +Node: Number Theoretic Functions107177 +Node: Integer Comparisons113336 +Node: Integer Logic and Bit Fiddling114714 +Node: I/O of Integers117337 +Node: Integer Random Numbers120221 +Node: Integer Import and Export122844 +Node: Miscellaneous Integer Functions126854 +Node: Integer Special Functions128714 +Node: Rational Number Functions131801 +Node: Initializing Rationals132994 +Node: Rational Conversions135187 +Node: Rational Arithmetic136918 +Node: Comparing Rationals138254 +Node: Applying Integer Functions139621 +Node: I/O of Rationals141104 +Node: Floating-point Functions142964 +Node: Initializing Floats145849 +Node: Assigning Floats149546 +Node: Simultaneous Float Init & Assign152113 +Node: Converting Floats153641 +Node: Float Arithmetic156889 +Node: Float Comparison158934 +Node: I/O of Floats160521 +Node: Miscellaneous Float Functions163119 +Node: Low-level Functions165019 +Node: Random Number Functions187301 +Node: Random State Initialization188369 +Node: Random State Seeding191231 +Node: Random State Miscellaneous192620 +Node: Formatted Output193261 +Node: Formatted Output Strings193506 +Node: Formatted Output Functions198720 +Node: C++ Formatted Output202795 +Node: Formatted Input205477 +Node: Formatted Input Strings205713 +Node: Formatted Input Functions210365 +Node: C++ Formatted Input213334 +Node: C++ Class Interface215237 +Node: C++ Interface General216238 +Node: C++ Interface Integers219308 +Node: C++ Interface Rationals222739 +Node: C++ Interface Floats226416 +Node: C++ Interface Random Numbers231708 +Node: C++ Interface Limitations234114 +Node: BSD Compatible Functions236934 +Node: Custom Allocation241645 +Node: Language Bindings245963 +Node: Algorithms249916 +Node: Multiplication Algorithms250616 +Node: Basecase Multiplication251594 +Node: Karatsuba Multiplication253502 +Node: Toom 3-Way Multiplication257130 +Node: Toom 4-Way Multiplication263544 +Node: FFT Multiplication264916 +Node: Other Multiplication270252 +Node: Unbalanced Multiplication272726 +Node: Division Algorithms273517 +Node: Single Limb Division273864 +Node: Basecase Division276755 +Node: Divide and Conquer Division277958 +Node: Exact Division280195 +Node: Exact Remainder283362 +Node: Small Quotient Division285654 +Node: Greatest Common Divisor Algorithms287252 +Node: Binary GCD287549 +Node: Lehmer's Algorithm290398 +Node: Subquadratic GCD292618 +Node: Extended GCD295077 +Node: Jacobi Symbol296389 +Node: Powering Algorithms297305 +Node: Normal Powering Algorithm297568 +Node: Modular Powering Algorithm298096 +Node: Root Extraction Algorithms299159 +Node: Square Root Algorithm299474 +Node: Nth Root Algorithm301615 +Node: Perfect Square Algorithm302400 +Node: Perfect Power Algorithm304486 +Node: Radix Conversion Algorithms305107 +Node: Binary to Radix305483 +Node: Radix to Binary309412 +Node: Other Algorithms311500 +Node: Prime Testing Algorithm311852 +Node: Factorial Algorithm313036 +Node: Binomial Coefficients Algorithm314439 +Node: Fibonacci Numbers Algorithm315333 +Node: Lucas Numbers Algorithm317807 +Node: Random Number Algorithms318528 +Node: Assembly Coding320649 +Node: Assembly Code Organisation321609 +Node: Assembly Basics322576 +Node: Assembly Carry Propagation323726 +Node: Assembly Cache Handling325557 +Node: Assembly Functional Units327718 +Node: Assembly Floating Point329331 +Node: Assembly SIMD Instructions333109 +Node: Assembly Software Pipelining334091 +Node: Assembly Loop Unrolling335153 +Node: Assembly Writing Guide337368 +Node: Internals340133 +Node: Integer Internals340645 +Node: Rational Internals342901 +Node: Float Internals344139 +Node: Raw Output Internals351553 +Node: C++ Interface Internals352747 +Node: Contributors356045 +Node: References360597 +Node: GNU Free Documentation License366255 +Node: Concept Index391424 +Node: Function Index437886 + +End Tag Table diff --git a/mpc/doc/mpc.info b/mpc/doc/mpc.info new file mode 100644 index 0000000000..6b41675908 --- /dev/null +++ b/mpc/doc/mpc.info @@ -0,0 +1,1799 @@ +This is mpc.info, produced by makeinfo version 5.2 from mpc.texi. + +This manual is for GNU MPC, a library for multiple precision complex +arithmetic, version 1.0.3 of February 2015. + + Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, +2011, 2012 INRIA + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections. A copy of the license is + included in the section entitled "GNU Free Documentation License." +INFO-DIR-SECTION GNU Packages +START-INFO-DIR-ENTRY +* mpc: (mpc)Multiple Precision Complex Library. +END-INFO-DIR-ENTRY + + +File: mpc.info, Node: Top, Next: Copying, Up: (dir) + +GNU MPC +******* + +This manual documents how to install and use the GNU Multiple Precision +Complex Library, version 1.0.3 + +* Menu: + +* Copying:: GNU MPC Copying Conditions (LGPL). +* Introduction to GNU MPC:: Brief introduction to GNU MPC. +* Installing GNU MPC:: How to configure and compile the GNU MPC library. +* Reporting Bugs:: How to usefully report bugs. +* GNU MPC Basics:: What every GNU MPC user should know. +* Complex Functions:: Functions for arithmetic on complex numbers. +* References:: +* Concept Index:: +* Function Index:: +* GNU Free Documentation License:: + + +File: mpc.info, Node: Copying, Next: Introduction to GNU MPC, Prev: Top, Up: Top + +GNU MPC Copying Conditions +************************** + +GNU MPC is free software; you can redistribute it and/or modify it under +the terms of the GNU Lesser General Public License as published by the +Free Software Foundation; either version 3 of the License, or (at your +option) any later version. + + GNU MPC is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser +General Public License for more details. + + You should have received a copy of the GNU Lesser General Public +License along with this program. If not, see +<http://www.gnu.org/licenses/>. + + +File: mpc.info, Node: Introduction to GNU MPC, Next: Installing GNU MPC, Prev: Copying, Up: Top + +1 Introduction to GNU MPC +************************* + +GNU MPC is a portable library written in C for arbitrary precision +arithmetic on complex numbers providing correct rounding. It implements +a multiprecision equivalent of the C99 standard. It builds upon the GNU +MP and the GNU MPFR libraries. + +1.1 How to use this Manual +========================== + +Everyone should read *note GNU MPC Basics::. If you need to install the +library yourself, you need to read *note Installing GNU MPC::, too. + + The remainder of the manual can be used for later reference, although +it is probably a good idea to skim through it. + + +File: mpc.info, Node: Installing GNU MPC, Next: Reporting Bugs, Prev: Introduction to GNU MPC, Up: Top + +2 Installing GNU MPC +******************** + +To build GNU MPC, you first have to install GNU MP (version 4.3.2 or +higher) and GNU MPFR (version 2.4.2 or higher) on your computer. You +need a C compiler; GCC version 4.4 or higher is recommended, since GNU +MPC may trigger a bug in previous versions, see the thread at +<http://lists.gforge.inria.fr/pipermail/mpc-discuss/2011-February/000823.html>. +And you need a standard Unix 'make' program, plus some other standard +Unix utility programs. + + Here are the steps needed to install the library on Unix systems: + + 1. 'tar xzf mpc-1.0.3.tar.gz' + + 2. 'cd mpc-1.0.3' + + 3. './configure' + + if GMP and GNU MPFR are installed into standard directories, that + is, directories that are searched by default by the compiler and + the linking tools. + + './configure --with-gmp=<gmp_install_dir>' + + is used to indicate a different location where GMP is installed. + Alternatively, you can specify directly GMP include and GMP lib + directories with './configure --with-gmp-lib=<gmp_lib_dir> + --with-gmp-include=<gmp_include_dir>'. + + './configure --with-mpfr=<mpfr_install_dir>' + + is used to indicate a different location where GNU MPFR is + installed. Alternatively, you can specify directly GNU MPFR + include and GNU MPFR lib directories with './configure + --with-mpf-lib=<mpfr_lib_dir> + --with-mpfr-include=<mpfr_include_dir>'. + + Another useful parameter is '--prefix', which can be used to + specify an alternative installation location instead of + '/usr/local'; see 'make install' below. + + To enable checking for memory leaks using 'valgrind' during 'make + check', add the parameter '--enable-valgrind-tests'. + + If for debugging purposes you wish to log calls to GNU MPC + functions from within your code, add the parameter + '--enable-logging'. In your code, replace the inclusion of 'mpc.h' + by 'mpc-log.h' and link the executable dynamically. Then all calls + to functions with only complex arguments are printed to 'stderr' in + the following form: First, the function name is given, followed by + its type such as 'c_cc', meaning that the function has one complex + result (one 'c' in front of the '_'), computed from two complex + arguments (two 'c' after the '_'). Then, the precisions of the + real and the imaginary part of the first result is given, followed + by the second one and so on. Finally, for each argument, the + precisions of its real and imaginary part are specified and the + argument itself is printed in hexadecimal via the function + 'mpc_out_str' (*note String and Stream Input and Output::). The + option requires a dynamic library, so it may not be combined with + '--disable-shared'. + + Use './configure --help' for an exhaustive list of parameters. + + 4. 'make' + + This compiles GNU MPC in the working directory. + + 5. 'make check' + + This will make sure GNU MPC was built correctly. + + If you get error messages, please report them to + 'mpc-discuss@lists.gforge.inria.fr' (*Note Reporting Bugs::, for + information on what to include in useful bug reports). + + 6. 'make install' + + This will copy the file 'mpc.h' to the directory + '/usr/local/include', the file 'libmpc.a' to the directory + '/usr/local/lib', and the file 'mpc.info' to the directory + '/usr/local/share/info' (or if you passed the '--prefix' option to + 'configure', using the prefix directory given as argument to + '--prefix' instead of '/usr/local'). Note: you need write + permissions on these directories. + +2.1 Other 'make' Targets +======================== + +There are some other useful make targets: + + * 'info' + + Create an info version of the manual, in 'mpc.info'. + + * 'pdf' + + Create a PDF version of the manual, in 'doc/mpc.pdf'. + + * 'dvi' + + Create a DVI version of the manual, in 'doc/mpc.dvi'. + + * 'ps' + + Create a Postscript version of the manual, in 'doc/mpc.ps'. + + * 'html' + + Create an HTML version of the manual, in several pages in the + directory 'doc/mpc.html'; if you want only one output HTML file, + then type 'makeinfo --html --no-split mpc.texi' instead. + + * 'clean' + + Delete all object files and archive files, but not the + configuration files. + + * 'distclean' + + Delete all files not included in the distribution. + + * 'uninstall' + + Delete all files copied by 'make install'. + +2.2 Known Build Problems +======================== + +On AIX, if GMP was built with the 64-bit ABI, before building and +testing GNU MPC, it might be necessary to set the 'OBJECT_MODE' +environment variable to 64 by, e.g., + + 'export OBJECT_MODE=64' + + This has been tested with the C compiler IBM XL C/C++ Enterprise +Edition V8.0 for AIX, version: 08.00.0000.0021, GMP 4.2.4 and GNU MPFR +2.4.1. + + Please report any other problems you encounter to +'mpc-discuss@lists.gforge.inria.fr'. *Note Reporting Bugs::. + + +File: mpc.info, Node: Reporting Bugs, Next: GNU MPC Basics, Prev: Installing GNU MPC, Up: Top + +3 Reporting Bugs +**************** + +If you think you have found a bug in the GNU MPC library, please +investigate and report it. We have made this library available to you, +and it is not to ask too much from you, to ask you to report the bugs +that you find. + + There are a few things you should think about when you put your bug +report together. + + You have to send us a test case that makes it possible for us to +reproduce the bug. Include instructions on how to run the test case. + + You also have to explain what is wrong; if you get a crash, or if the +results printed are incorrect and in that case, in what way. + + Please include compiler version information in your bug report. This +can be extracted using 'gcc -v', or 'cc -V' on some machines. Also, +include the output from 'uname -a'. + + If your bug report is good, we will do our best to help you to get a +corrected version of the library; if the bug report is poor, we will not +do anything about it (aside of chiding you to send better bug reports). + + Send your bug report to: 'mpc-discuss@lists.gforge.inria.fr'. + + If you think something in this manual is unclear, or downright +incorrect, or if the language needs to be improved, please send a note +to the same address. + + +File: mpc.info, Node: GNU MPC Basics, Next: Complex Functions, Prev: Reporting Bugs, Up: Top + +4 GNU MPC Basics +**************** + +All declarations needed to use GNU MPC are collected in the include file +'mpc.h'. It is designed to work with both C and C++ compilers. You +should include that file in any program using the GNU MPC library by +adding the line + #include "mpc.h" + +4.1 Nomenclature and Types +========================== + +"Complex number" or "Complex" for short, is a pair of two arbitrary +precision floating-point numbers (for the real and imaginary parts). +The C data type for such objects is 'mpc_t'. + +The "Precision" is the number of bits used to represent the mantissa of +the real and imaginary parts; the corresponding C data type is +'mpfr_prec_t'. For more details on the allowed precision range, *note +(mpfr.info)Nomenclature and Types::. + +The "rounding mode" specifies the way to round the result of a complex +operation, in case the exact result can not be represented exactly in +the destination mantissa; the corresponding C data type is 'mpc_rnd_t'. +A complex rounding mode is a pair of two rounding modes: one for the +real part, one for the imaginary part. + +4.2 Function Classes +==================== + +There is only one class of functions in the GNU MPC library, namely +functions for complex arithmetic. The function names begin with 'mpc_'. +The associated type is 'mpc_t'. + +4.3 GNU MPC Variable Conventions +================================ + +As a general rule, all GNU MPC functions expect output arguments before +input arguments. This notation is based on an analogy with the +assignment operator. + + GNU MPC allows you to use the same variable for both input and output +in the same expression. For example, the main function for +floating-point multiplication, 'mpc_mul', can be used like this: +'mpc_mul (x, x, x, rnd_mode)'. This computes the square of X with +rounding mode 'rnd_mode' and puts the result back in X. + + Before you can assign to an GNU MPC variable, you need to initialize +it by calling one of the special initialization functions. When you are +done with a variable, you need to clear it out, using one of the +functions for that purpose. + + A variable should only be initialized once, or at least cleared out +between each initialization. After a variable has been initialized, it +may be assigned to any number of times. + + For efficiency reasons, avoid to initialize and clear out a variable +in loops. Instead, initialize it before entering the loop, and clear it +out after the loop has exited. + + You do not need to be concerned about allocating additional space for +GNU MPC variables, since each of its real and imaginary part has a +mantissa of fixed size. Hence unless you change its precision, or clear +and reinitialize it, a complex variable will have the same allocated +space during all its life. + +4.4 Rounding Modes +================== + +A complex rounding mode is of the form 'MPC_RNDxy' where 'x' and 'y' are +one of 'N' (to nearest), 'Z' (towards zero), 'U' (towards plus +infinity), 'D' (towards minus infinity). The first letter refers to the +rounding mode for the real part, and the second one for the imaginary +part. For example 'MPC_RNDZU' indicates to round the real part towards +zero, and the imaginary part towards plus infinity. + + The 'round to nearest' mode works as in the IEEE P754 standard: in +case the number to be rounded lies exactly in the middle of two +representable numbers, it is rounded to the one with the least +significant bit set to zero. For example, the number 5, which is +represented by (101) in binary, is rounded to (100)=4 with a precision +of two bits, and not to (110)=6. + +4.5 Return Value +================ + +Most GNU MPC functions have a return value of type 'int', which is used +to indicate the position of the rounded real and imaginary parts with +respect to the exact (infinite precision) values. If this integer is +'i', the macros 'MPC_INEX_RE(i)' and 'MPC_INEX_IM(i)' give 0 if the +corresponding rounded value is exact, a negative value if the rounded +value is less than the exact one, and a positive value if it is greater +than the exact one. Similarly, functions computing a result of type +'mpfr_t' return an integer that is 0, positive or negative depending on +whether the rounded value is the same, larger or smaller then the exact +result. + + Some functions, such as 'mpc_sin_cos', compute two complex results; +the macros 'MPC_INEX1(i)' and 'MPC_INEX2(i)', applied to the return +value 'i' of such a function, yield the exactness value corresponding to +the first or the second computed value, respectively. + +4.6 Branch Cuts And Special Values +================================== + +Some complex functions have branch cuts, across which the function is +discontinous. In GNU MPC, the branch cuts chosen are the same as those +specified for the corresponding functions in the ISO C99 standard. + + Likewise, when evaluated at a point whose real or imaginary part is +either infinite or a NaN or a signed zero, a function returns the same +value as those specified for the corresponding function in the ISO C99 +standard. + + +File: mpc.info, Node: Complex Functions, Next: References, Prev: GNU MPC Basics, Up: Top + +5 Complex Functions +******************* + +The complex functions expect arguments of type 'mpc_t'. + + The GNU MPC floating-point functions have an interface that is +similar to the GNU MP integer functions. The function prefix for +operations on complex numbers is 'mpc_'. + + The precision of a computation is defined as follows: Compute the +requested operation exactly (with "infinite precision"), and round the +result to the destination variable precision with the given rounding +mode. + + The GNU MPC complex functions are intended to be a smooth extension +of the IEEE P754 arithmetic. The results obtained on one computer +should not differ from the results obtained on a computer with a +different word size. + +* Menu: + +* Initializing Complex Numbers:: +* Assigning Complex Numbers:: +* Converting Complex Numbers:: +* String and Stream Input and Output:: +* Complex Comparison:: +* Projection & Decomposing:: +* Basic Arithmetic:: +* Power Functions and Logarithm:: +* Trigonometric Functions:: +* Miscellaneous Complex Functions:: +* Advanced Functions:: +* Internals:: + + +File: mpc.info, Node: Initializing Complex Numbers, Next: Assigning Complex Numbers, Up: Complex Functions + +5.1 Initialization Functions +============================ + +An 'mpc_t' object must be initialized before storing the first value in +it. The functions 'mpc_init2' and 'mpc_init3' are used for that +purpose. + + -- Function: void mpc_init2 (mpc_t Z, mpfr_prec_t PREC) + Initialize Z to precision PREC bits and set its real and imaginary + parts to NaN. Normally, a variable should be initialized once only + or at least be cleared, using 'mpc_clear', between initializations. + + -- Function: void mpc_init3 (mpc_t Z, mpfr_prec_t PREC_R, mpfr_prec_t + PREC_I) + Initialize Z with the precision of its real part being PREC_R bits + and the precision of its imaginary part being PREC_I bits, and set + the real and imaginary parts to NaN. + + -- Function: void mpc_clear (mpc_t Z) + Free the space occupied by Z. Make sure to call this function for + all 'mpc_t' variables when you are done with them. + + Here is an example on how to initialize complex variables: + { + mpc_t x, y; + mpc_init2 (x, 256); /* precision _exactly_ 256 bits */ + mpc_init3 (y, 100, 50); /* 100/50 bits for the real/imaginary part */ + ... + mpc_clear (x); + mpc_clear (y); + } + + The following function is useful for changing the precision during a +calculation. A typical use would be for adjusting the precision +gradually in iterative algorithms like Newton-Raphson, making the +computation precision closely match the actual accurate part of the +numbers. + + -- Function: void mpc_set_prec (mpc_t X, mpfr_prec_t PREC) + Reset the precision of X to be *exactly* PREC bits, and set its + real/imaginary parts to NaN. The previous value stored in X is + lost. It is equivalent to a call to 'mpc_clear(x)' followed by a + call to 'mpc_init2(x, prec)', but more efficient as no allocation + is done in case the current allocated space for the mantissa of X + is sufficient. + + -- Function: mpfr_prec_t mpc_get_prec (mpc_t X) + If the real and imaginary part of X have the same precision, it is + returned, otherwise, 0 is returned. + + -- Function: void mpc_get_prec2 (mpfr_prec_t* PR, mpfr_prec_t* PI, + mpc_t X) + Returns the precision of the real part of X via PR and of its + imaginary part via PI. + + +File: mpc.info, Node: Assigning Complex Numbers, Next: Converting Complex Numbers, Prev: Initializing Complex Numbers, Up: Complex Functions + +5.2 Assignment Functions +======================== + +These functions assign new values to already initialized complex numbers +(*note Initializing Complex Numbers::). When using any functions with +'intmax_t' or 'uintmax_t' parameters, you must include '<stdint.h>' or +'<inttypes.h>' _before_ 'mpc.h', to allow 'mpc.h' to define prototypes +for these functions. Similarly, functions with parameters of type +'complex' or 'long complex' are defined only if '<complex.h>' is +included _before_ 'mpc.h'. If you need assignment functions that are +not in the current API, you can define them using the 'MPC_SET_X_Y' +macro (*note Advanced Functions::). + + -- Function: int mpc_set (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set the value of ROP from OP, rounded to the precision of ROP with + the given rounding mode RND. + + -- Function: int mpc_set_ui (mpc_t ROP, unsigned long int OP, mpc_rnd_t + RND) + -- Function: int mpc_set_si (mpc_t ROP, long int OP, mpc_rnd_t RND) + -- Function: int mpc_set_uj (mpc_t ROP, uintmax_t OP, mpc_rnd_t RND) + -- Function: int mpc_set_sj (mpc_t ROP, intmax_t OP, mpc_rnd_t RND) + -- Function: int mpc_set_d (mpc_t ROP, double OP, mpc_rnd_t RND) + -- Function: int mpc_set_ld (mpc_t ROP, long double OP, mpc_rnd_t RND) + -- Function: int mpc_set_dc (mpc_t ROP, double _Complex OP, mpc_rnd_t + RND) + -- Function: int mpc_set_ldc (mpc_t ROP, long double _Complex OP, + mpc_rnd_t RND) + -- Function: int mpc_set_z (mpc_t ROP, mpz_t OP mpc_rnd_t RND) + -- Function: int mpc_set_q (mpc_t ROP, mpq_t OP mpc_rnd_t RND) + -- Function: int mpc_set_f (mpc_t ROP, mpf_t OP mpc_rnd_t RND) + -- Function: int mpc_set_fr (mpc_t ROP, mpfr_t OP, mpc_rnd_t RND) + Set the value of ROP from OP, rounded to the precision of ROP with + the given rounding mode RND. The argument OP is interpreted as + real, so the imaginary part of ROP is set to zero with a positive + sign. Please note that even a 'long int' may have to be rounded, + if the destination precision is less than the machine word width. + For 'mpc_set_d', be careful that the input number OP may not be + exactly representable as a double-precision number (this happens + for 0.1 for instance), in which case it is first rounded by the C + compiler to a double-precision number, and then only to a complex + number. + + -- Function: int mpc_set_ui_ui (mpc_t ROP, unsigned long int OP1, + unsigned long int OP2, mpc_rnd_t RND) + -- Function: int mpc_set_si_si (mpc_t ROP, long int OP1, long int OP2, + mpc_rnd_t RND) + -- Function: int mpc_set_uj_uj (mpc_t ROP, uintmax_t OP1, uintmax_t + OP2, mpc_rnd_t RND) + -- Function: int mpc_set_sj_sj (mpc_t ROP, intmax_t OP1, intmax_t OP2, + mpc_rnd_t RND) + -- Function: int mpc_set_d_d (mpc_t ROP, double OP1, double OP2, + mpc_rnd_t RND) + -- Function: int mpc_set_ld_ld (mpc_t ROP, long double OP1, long double + OP2, mpc_rnd_t RND) + -- Function: int mpc_set_z_z (mpc_t ROP, mpz_t OP1, mpz_t OP2, + mpc_rnd_t RND) + -- Function: int mpc_set_q_q (mpc_t ROP, mpq_t OP1, mpq_t OP2, + mpc_rnd_t RND) + -- Function: int mpc_set_f_f (mpc_t ROP, mpf_t OP1, mpf_t OP2, + mpc_rnd_t RND) + -- Function: int mpc_set_fr_fr (mpc_t ROP, mpfr_t OP1, mpfr_t OP2, + mpc_rnd_t RND) + Set the real part of ROP from OP1, and its imaginary part from OP2, + according to the rounding mode RND. + + Beware that the behaviour of 'mpc_set_fr_fr' is undefined if OP1 or + OP2 is a pointer to the real or imaginary part of ROP. To exchange + the real and the imaginary part of a complex number, either use + 'mpfr_swap (mpc_realref (rop), mpc_imagref (rop))', which also + exchanges the precisions of the two parts; or use a temporary + variable. + + For functions assigning complex variables from strings or input +streams, *note String and Stream Input and Output::. + + -- Function: void mpc_set_nan (mpc_t ROP) + Set ROP to Nan+i*NaN. + + -- Function: void mpc_swap (mpc_t OP1, mpc_t OP2) + Swap the values of OP1 and OP2 efficiently. Warning: The + precisions are exchanged, too; in case these are different, + 'mpc_swap' is thus not equivalent to three 'mpc_set' calls using a + third auxiliary variable. + + +File: mpc.info, Node: Converting Complex Numbers, Next: String and Stream Input and Output, Prev: Assigning Complex Numbers, Up: Complex Functions + +5.3 Conversion Functions +======================== + +The following functions are available only if '<complex.h>' is included +_before_ 'mpc.h'. + + -- Function: double _Complex mpc_get_dc (mpc_t OP, mpc_rnd_t RND) + -- Function: long double _Complex mpc_get_ldc (mpc_t OP, mpc_rnd_t RND) + Convert OP to a C complex number, using the rounding mode RND. + + For functions converting complex variables to strings or stream +output, *note String and Stream Input and Output::. + + +File: mpc.info, Node: String and Stream Input and Output, Next: Complex Comparison, Prev: Converting Complex Numbers, Up: Complex Functions + +5.4 String and Stream Input and Output +====================================== + + -- Function: int mpc_strtoc (mpc_t ROP, const char *NPTR, char + **ENDPTR, int BASE, mpc_rnd_t RND) + Read a complex number from a string NPTR in base BASE, rounded to + the precision of ROP with the given rounding mode RND. The BASE + must be either 0 or a number from 2 to 36 (otherwise the behaviour + is undefined). If NPTR starts with valid data, the result is + stored in ROP, the usual inexact value is returned (*note Return + Value: return-value.) and, if ENDPTR is not the null pointer, + *ENDPTR points to the character just after the valid data. + Otherwise, ROP is set to 'NaN + i * NaN', -1 is returned and, if + ENDPTR is not the null pointer, the value of NPTR is stored in the + location referenced by ENDPTR. + + The expected form of a complex number string is either a real + number (an optional leading whitespace, an optional sign followed + by a floating-point number), or a pair of real numbers in + parentheses separated by whitespace. If a real number is read, the + missing imaginary part is set to +0. The form of a floating-point + number depends on the base and is described in the documentation of + 'mpfr_strtofr' (*note (mpfr.info)Assignment Functions::). For + instance, '"3.1415926"', '"(1.25e+7 +.17)"', '"(@nan@ 2)"' and + '"(-0 -7)"' are valid strings for BASE = 10. If BASE = 0, then a + prefix may be used to indicate the base in which the floating-point + number is written. Use prefix '0b' for binary numbers, prefix '0x' + for hexadecimal numbers, and no prefix for decimal numbers. The + real and imaginary part may then be written in different bases. + For instance, '"(1.024e+3 +2.05e+3)"' and '"(0b1p+10 +0x802)"' are + valid strings for 'base'=0 and represent the same value. + + -- Function: int mpc_set_str (mpc_t ROP, const char *S, int BASE, + mpc_rnd_t rnd) + Set ROP to the value of the string S in base BASE, rounded to the + precision of ROP with the given rounding mode RND. See the + documentation of 'mpc_strtoc' for a detailed description of the + valid string formats. Contrarily to 'mpc_strtoc', 'mpc_set_str' + requires the _whole_ string to represent a valid complex number + (potentially followed by additional white space). This function + returns the usual inexact value (*note Return Value: return-value.) + if the entire string up to the final null character is a valid + number in base BASE; otherwise it returns -1, and ROP is set to + NaN+i*NaN. + + -- Function: char * mpc_get_str (int B, size_t N, mpc_t OP, mpc_rnd_t + RND) + Convert OP to a string containing its real and imaginary parts, + separated by a space and enclosed in a pair of parentheses. The + numbers are written in base B (which may vary from 2 to 36) and + rounded according to RND. The number of significant digits, at + least 2, is given by N. It is also possible to let N be zero, in + which case the number of digits is chosen large enough so that + re-reading the printed value with the same precision, assuming both + output and input use rounding to nearest, will recover the original + value of OP. Note that 'mpc_get_str' uses the decimal point of the + current locale if available, and '.' otherwise. + + The string is generated using the current memory allocation + function ('malloc' by default, unless it has been modified using + the custom memory allocation interface of 'gmp'); once it is not + needed any more, it should be freed by calling 'mpc_free_str'. + + -- Function: void mpc_free_str (char *STR) + Free the string STR, which needs to have been allocated by a call + to 'mpc_get_str'. + + The following two functions read numbers from input streams and write +them to output streams. When using any of these functions, you need to +include 'stdio.h' _before_ 'mpc.h'. + + -- Function: int mpc_inp_str (mpc_t ROP, FILE *STREAM, size_t *READ, + int BASE, mpc_rnd_t RND) + Input a string in base BASE in the same format as for 'mpc_strtoc' + from stdio stream STREAM, rounded according to RND, and put the + read complex number into ROP. If STREAM is the null pointer, ROP + is read from 'stdin'. Return the usual inexact value; if an error + occurs, set ROP to 'NaN + i * NaN' and return -1. If READ is not + the null pointer, it is set to the number of read characters. + + Unlike 'mpc_strtoc', the function 'mpc_inp_str' does not possess + perfect knowledge of the string to transform and has to read it + character by character, so it behaves slightly differently: It + tries to read a string describing a complex number and processes + this string through a call to 'mpc_set_str'. Precisely, after + skipping optional whitespace, a minimal string is read according to + the regular expression 'mpfr | '(' \s* mpfr \s+ mpfr \s* ')'', + where '\s' denotes a whitespace, and 'mpfr' is either a string + containing neither whitespaces nor parentheses, or + 'nan(n-char-sequence)' or '@nan@(n-char-sequence)' (regardless of + capitalisation) with 'n-char-sequence' a string of ascii letters, + digits or ''_''. + + For instance, upon input of '"nan(13 1)"', the function + 'mpc_inp_str' starts to recognise a value of NaN followed by an + n-char-sequence indicated by the opening parenthesis; as soon as + the space is reached, it becocmes clear that the expression in + parentheses is not an n-char-sequence, and the error flag -1 is + returned after 6 characters have been consumed from the stream (the + whitespace itself remaining in the stream). The function + 'mpc_strtoc', on the other hand, may track back when reaching the + whitespace; it treats the string as the two successive complex + numbers 'NaN + i * 0' and '13 + i'. It is thus recommended to have + a whitespace follow each floating point number to avoid this + problem. + + -- Function: size_t mpc_out_str (FILE *STREAM, int BASE, size_t + N_DIGITS, mpc_t OP, mpc_rnd_t RND) + Output OP on stdio stream STREAM in base BASE, rounded according to + RND, in the same format as for 'mpc_strtoc' If STREAM is the null + pointer, ROP is written to 'stdout'. + + Return the number of characters written. + + +File: mpc.info, Node: Complex Comparison, Next: Projection & Decomposing, Prev: String and Stream Input and Output, Up: Complex Functions + +5.5 Comparison Functions +======================== + + -- Function: int mpc_cmp (mpc_t OP1, mpc_t OP2) + -- Function: int mpc_cmp_si_si (mpc_t OP1, long int OP2R, long int + OP2I) + -- Macro: int mpc_cmp_si (mpc_t OP1, long int OP2) + + Compare OP1 and OP2, where in the case of 'mpc_cmp_si_si', OP2 is + taken to be OP2R + i OP2I. The return value C can be decomposed + into 'x = MPC_INEX_RE(c)' and 'y = MPC_INEX_IM(c)', such that X is + positive if the real part of OP1 is greater than that of OP2, zero + if both real parts are equal, and negative if the real part of OP1 + is less than that of OP2, and likewise for Y. Both OP1 and OP2 are + considered to their full own precision, which may differ. It is + not allowed that one of the operands has a NaN (Not-a-Number) part. + + The storage of the return value is such that equality can be simply + checked with 'mpc_cmp (op1, op2) == 0'. + + +File: mpc.info, Node: Projection & Decomposing, Next: Basic Arithmetic, Prev: Complex Comparison, Up: Complex Functions + +5.6 Projection and Decomposing Functions +======================================== + + -- Function: int mpc_real (mpfr_t ROP, mpc_t OP, mpfr_rnd_t RND) + Set ROP to the value of the real part of OP rounded in the + direction RND. + + -- Function: int mpc_imag (mpfr_t ROP, mpc_t OP, mpfr_rnd_t RND) + Set ROP to the value of the imaginary part of OP rounded in the + direction RND. + + -- Macro: mpfr_t mpc_realref (mpc_t OP) + -- Macro: mpfr_t mpc_imagref (mpc_t OP) + Return a reference to the real part and imaginary part of OP, + respectively. The 'mpfr' functions can be used on the result of + these macros (note that the 'mpfr_t' type is itself a pointer). + + -- Function: int mpc_arg (mpfr_t ROP, mpc_t OP, mpfr_rnd_t RND) + Set ROP to the argument of OP, with a branch cut along the negative + real axis. + + -- Function: int mpc_proj (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Compute a projection of OP onto the Riemann sphere. Set ROP to OP + rounded in the direction RND, except when at least one part of OP + is infinite (even if the other part is a NaN) in which case the + real part of ROP is set to plus infinity and its imaginary part to + a signed zero with the same sign as the imaginary part of OP. + + +File: mpc.info, Node: Basic Arithmetic, Next: Power Functions and Logarithm, Prev: Projection & Decomposing, Up: Complex Functions + +5.7 Basic Arithmetic Functions +============================== + +All the following functions are designed in such a way that, when +working with real numbers instead of complex numbers, their complexity +should essentially be the same as with the GNU MPFR library, with only a +marginal overhead due to the GNU MPC layer. + + -- Function: int mpc_add (mpc_t ROP, mpc_t OP1, mpc_t OP2, mpc_rnd_t + RND) + -- Function: int mpc_add_ui (mpc_t ROP, mpc_t OP1, unsigned long int + OP2, mpc_rnd_t RND) + -- Function: int mpc_add_fr (mpc_t ROP, mpc_t OP1, mpfr_t OP2, + mpc_rnd_t RND) + Set ROP to OP1 + OP2 rounded according to RND. + + -- Function: int mpc_sub (mpc_t ROP, mpc_t OP1, mpc_t OP2, mpc_rnd_t + RND) + -- Function: int mpc_sub_fr (mpc_t ROP, mpc_t OP1, mpfr_t OP2, + mpc_rnd_t RND) + -- Function: int mpc_fr_sub (mpc_t ROP, mpfr_t OP1, mpc_t OP2, + mpc_rnd_t RND) + -- Function: int mpc_sub_ui (mpc_t ROP, mpc_t OP1, unsigned long int + OP2, mpc_rnd_t RND) + -- Macro: int mpc_ui_sub (mpc_t ROP, unsigned long int OP1, mpc_t OP2, + mpc_rnd_t RND) + -- Function: int mpc_ui_ui_sub (mpc_t ROP, unsigned long int RE1, + unsigned long int IM1, mpc_t OP2, mpc_rnd_t RND) + Set ROP to OP1 - OP2 rounded according to RND. For + 'mpc_ui_ui_sub', OP1 is RE1 + IM1. + + -- Function: int mpc_neg (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to -OP rounded according to RND. Just changes the sign if + ROP and OP are the same variable. + + -- Function: int mpc_mul (mpc_t ROP, mpc_t OP1, mpc_t OP2, mpc_rnd_t + RND) + -- Function: int mpc_mul_ui (mpc_t ROP, mpc_t OP1, unsigned long int + OP2, mpc_rnd_t RND) + -- Function: int mpc_mul_si (mpc_t ROP, mpc_t OP1, long int OP2, + mpc_rnd_t RND) + -- Function: int mpc_mul_fr (mpc_t ROP, mpc_t OP1, mpfr_t OP2, + mpc_rnd_t RND) + Set ROP to OP1 times OP2 rounded according to RND. Note: for + 'mpc_mul', in case OP1 and OP2 have the same value, use 'mpc_sqr' + for better efficiency. + + -- Function: int mpc_mul_i (mpc_t ROP, mpc_t OP, int SGN, mpc_rnd_t + RND) + Set ROP to OP times the imaginary unit i if SGN is non-negative, + set ROP to OP times -i otherwise, in both cases rounded according + to RND. + + -- Function: int mpc_sqr (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the square of OP rounded according to RND. + + -- Function: int mpc_fma (mpc_t ROP, mpc_t OP1, mpc_t OP2, mpc_t OP3, + mpc_rnd_t RND) + Set ROP to OP1*OP2+OP3, rounded according to RND, with only one + final rounding. + + -- Function: int mpc_div (mpc_t ROP, mpc_t OP1, mpc_t OP2, mpc_rnd_t + RND) + -- Function: int mpc_div_ui (mpc_t ROP, mpc_t OP1, unsigned long int + OP2, mpc_rnd_t RND) + -- Function: int mpc_div_fr (mpc_t ROP, mpc_t OP1, mpfr_t OP2, + mpc_rnd_t RND) + -- Function: int mpc_ui_div (mpc_t ROP, unsigned long int OP1, mpc_t + OP2, mpc_rnd_t RND) + -- Function: int mpc_fr_div (mpc_t ROP, mpfr_t OP1, mpc_t OP2, + mpc_rnd_t RND) + Set ROP to OP1/OP2 rounded according to RND. + + -- Function: int mpc_conj (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the conjugate of OP rounded according to RND. Just + changes the sign of the imaginary part if ROP and OP are the same + variable. + + -- Function: int mpc_abs (mpfr_t ROP, mpc_t OP, mpfr_rnd_t RND) + Set the floating-point number ROP to the absolute value of OP, + rounded in the direction RND. + + -- Function: int mpc_norm (mpfr_t ROP, mpc_t OP, mpfr_rnd_t RND) + Set the floating-point number ROP to the norm of OP (i.e., the + square of its absolute value), rounded in the direction RND. + + -- Function: int mpc_mul_2ui (mpc_t ROP, mpc_t OP1, unsigned long int + OP2, mpc_rnd_t RND) + -- Function: int mpc_mul_2si (mpc_t ROP, mpc_t OP1, long int OP2, + mpc_rnd_t RND) + Set ROP to OP1 times 2 raised to OP2 rounded according to RND. + Just modifies the exponents of the real and imaginary parts by OP2 + when ROP and OP1 are identical. + + -- Function: int mpc_div_2ui (mpc_t ROP, mpc_t OP1, unsigned long int + OP2, mpc_rnd_t RND) + -- Function: int mpc_div_2si (mpc_t ROP, mpc_t OP1, long int OP2, + mpc_rnd_t RND) + Set ROP to OP1 divided by 2 raised to OP2 rounded according to RND. + Just modifies the exponents of the real and imaginary parts by OP2 + when ROP and OP1 are identical. + + +File: mpc.info, Node: Power Functions and Logarithm, Next: Trigonometric Functions, Prev: Basic Arithmetic, Up: Complex Functions + +5.8 Power Functions and Logarithm +================================= + + -- Function: int mpc_sqrt (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the square root of OP rounded according to RND. The + returned value ROP has a non-negative real part, and if its real + part is zero, a non-negative imaginary part. + + -- Function: int mpc_pow (mpc_t ROP, mpc_t OP1, mpc_t OP2, mpc_rnd_t + RND) + -- Function: int mpc_pow_d (mpc_t ROP, mpc_t OP1, double OP2, mpc_rnd_t + RND) + -- Function: int mpc_pow_ld (mpc_t ROP, mpc_t OP1, long double OP2, + mpc_rnd_t RND) + -- Function: int mpc_pow_si (mpc_t ROP, mpc_t OP1, long OP2, mpc_rnd_t + RND) + -- Function: int mpc_pow_ui (mpc_t ROP, mpc_t OP1, unsigned long OP2, + mpc_rnd_t RND) + -- Function: int mpc_pow_z (mpc_t ROP, mpc_t OP1, mpz_t OP2, mpc_rnd_t + RND) + -- Function: int mpc_pow_fr (mpc_t ROP, mpc_t OP1, mpfr_t OP2, + mpc_rnd_t RND) + Set ROP to OP1 raised to the power OP2, rounded according to RND. + For 'mpc_pow_d', 'mpc_pow_ld', 'mpc_pow_si', 'mpc_pow_ui', + 'mpc_pow_z' and 'mpc_pow_fr', the imaginary part of OP2 is + considered as +0. When both OP1 and OP2 are zero, the result has + real part 1, and imaginary part 0, with sign being the opposite of + that of OP2. + + -- Function: int mpc_exp (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the exponential of OP, rounded according to RND with the + precision of ROP. + + -- Function: int mpc_log (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + -- Function: int mpc_log10 (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the natural and base-10 logarithm of OP respectively, + rounded according to RND with the precision of ROP. The principal + branch is chosen, with the branch cut on the negative real axis, so + that the imaginary part of the result lies in ]-\pi , \pi] and + ]-\pi/log(10) , \pi/log(10)] respectively. + + +File: mpc.info, Node: Trigonometric Functions, Next: Miscellaneous Complex Functions, Prev: Power Functions and Logarithm, Up: Complex Functions + +5.9 Trigonometric Functions +=========================== + + -- Function: int mpc_sin (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the sine of OP, rounded according to RND with the + precision of ROP. + + -- Function: int mpc_cos (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the cosine of OP, rounded according to RND with the + precision of ROP. + + -- Function: int mpc_sin_cos (mpc_t ROP_SIN, mpc_t ROP_COS, mpc_t OP, + mpc_rnd_t RND_SIN, mpc_rnd_t RND_COS) + Set ROP_SIN to the sine of OP, rounded according to RND_SIN with + the precision of ROP_SIN, and ROP_COS to the cosine of OP, rounded + according to RND_COS with the precision of ROP_COS. + + -- Function: int mpc_tan (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the tangent of OP, rounded according to RND with the + precision of ROP. + + -- Function: int mpc_sinh (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the hyperbolic sine of OP, rounded according to RND with + the precision of ROP. + + -- Function: int mpc_cosh (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the hyperbolic cosine of OP, rounded according to RND + with the precision of ROP. + + -- Function: int mpc_tanh (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the hyperbolic tangent of OP, rounded according to RND + with the precision of ROP. + + -- Function: int mpc_asin (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + -- Function: int mpc_acos (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + -- Function: int mpc_atan (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the inverse sine, inverse cosine, inverse tangent of OP, + rounded according to RND with the precision of ROP. + + -- Function: int mpc_asinh (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + -- Function: int mpc_acosh (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + -- Function: int mpc_atanh (mpc_t ROP, mpc_t OP, mpc_rnd_t RND) + Set ROP to the inverse hyperbolic sine, inverse hyperbolic cosine, + inverse hyperbolic tangent of OP, rounded according to RND with the + precision of ROP. The branch cut of MPC_ACOSH is (-\infty, 1). + + +File: mpc.info, Node: Miscellaneous Complex Functions, Next: Advanced Functions, Prev: Trigonometric Functions, Up: Complex Functions + +5.10 Miscellaneous Functions +============================ + + -- Function: int mpc_urandom (mpc_t ROP, gmp_randstate_t STATE) + Generate a uniformly distributed random complex in the unit square + [0, 1] x [0, 1]. Return 0, unless an exponent in the real or + imaginary part is not in the current exponent range, in which case + that part is set to NaN and a zero value is returned. The second + argument is a 'gmp_randstate_t' structure which should be created + using the GMP 'rand_init' function, see the GMP manual. + + -- Function: const char * mpc_get_version (void) + Return the GNU MPC version, as a null-terminated string. + + -- Macro: MPC_VERSION + -- Macro: MPC_VERSION_MAJOR + -- Macro: MPC_VERSION_MINOR + -- Macro: MPC_VERSION_PATCHLEVEL + -- Macro: MPC_VERSION_STRING + 'MPC_VERSION' is the version of GNU MPC as a preprocessing + constant. 'MPC_VERSION_MAJOR', 'MPC_VERSION_MINOR' and + 'MPC_VERSION_PATCHLEVEL' are respectively the major, minor and + patch level of GNU MPC version, as preprocessing constants. + 'MPC_VERSION_STRING' is the version as a string constant, which can + be compared to the result of 'mpc_get_version' to check at run time + the header file and library used match: + if (strcmp (mpc_get_version (), MPC_VERSION_STRING)) + fprintf (stderr, "Warning: header and library do not match\n"); + Note: Obtaining different strings is not necessarily an error, as + in general, a program compiled with some old GNU MPC version can be + dynamically linked with a newer GNU MPC library version (if allowed + by the library versioning system). + + -- Macro: long MPC_VERSION_NUM (MAJOR, MINOR, PATCHLEVEL) + Create an integer in the same format as used by 'MPC_VERSION' from + the given MAJOR, MINOR and PATCHLEVEL. Here is an example of how + to check the GNU MPC version at compile time: + #if (!defined(MPC_VERSION) || (MPC_VERSION<MPC_VERSION_NUM(2,1,0))) + # error "Wrong GNU MPC version." + #endif + + +File: mpc.info, Node: Advanced Functions, Next: Internals, Prev: Miscellaneous Complex Functions, Up: Complex Functions + +5.11 Advanced Functions +======================= + + -- Macro: MPC_SET_X_Y (REAL_SUFFIX, IMAG_SUFFIX, ROP, REAL, IMAG, RND) + The macro MPC_SET_X_Y is designed to serve as the body of an + assignment function and cannot be used by itself. The REAL_SUFFIX + and IMAG_SUFFIX parameters are the types of the real and imaginary + part, that is, the 'x' in the 'mpfr_set_x' function one would use + to set the part; for the mpfr type, use 'fr'. REAL (respectively + IMAG) is the value you want to assign to the real (resp. + imaginary) part, its type must conform to REAL_SUFFIX (resp. + IMAG_SUFFIX). RND is the 'mpc_rnd_t' rounding mode. The return + value is the usual inexact value (*note Return Value: + return-value.). + + For instance, you can define mpc_set_ui_fr as follows: + int mpc_set_ui_fr (mpc_t rop, long int re, double im, mpc_rnd_t rnd) + MPC_SET_X_Y (ui, fr, rop, re, im, rnd); + + +File: mpc.info, Node: Internals, Prev: Advanced Functions, Up: Complex Functions + +5.12 Internals +============== + +These macros and functions are mainly designed for the implementation of +GNU MPC, but may be useful for users too. However, no upward +compatibility is guaranteed. You need to include 'mpc-impl.h' to use +them. + + The macro 'MPC_MAX_PREC(z)' gives the maximum of the precisions of +the real and imaginary parts of a complex number. + + +File: mpc.info, Node: References, Next: Concept Index, Prev: Complex Functions, Up: Top + +References +********** + + * Torbjo"rn Granlund et al. 'gmp' - GNU multiprecision library. + Version 4.2.4, <http://gmplib.org/>. + + * Guillaume Hanrot, Vincent Lefe`vre, Patrick Pe'lissier, Paul + Zimmermann et al. 'mpfr' - A library for multiple-precision + floating-point computations with exact rounding. Version 2.4.1, + <http://www.mpfr.org>. + + * IEEE standard for binary floating-point arithmetic, Technical + Report ANSI-IEEE Standard 754-1985, New York, 1985. Approved March + 21, 1985: IEEE Standards Board; approved July 26, 1985: American + National Standards Institute, 18 pages. + + * Donald E. Knuth, "The Art of Computer Programming", vol 2, + "Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981. + + * ISO/IEC 9899:1999, Programming languages — C. + + +File: mpc.info, Node: Concept Index, Next: Function Index, Prev: References, Up: Top + +Concept Index +************* + + +* Menu: + +* Arithmetic functions: Basic Arithmetic. (line 6) +* Comparison functions: Complex Comparison. (line 6) +* Complex arithmetic functions: Basic Arithmetic. (line 6) +* Complex assignment functions: Assigning Complex Numbers. + (line 6) +* Complex comparisons functions: Complex Comparison. (line 6) +* Complex functions: Complex Functions. (line 6) +* Complex number: GNU MPC Basics. (line 15) +* Conditions for copying GNU MPC: Copying. (line 6) +* Conversion functions: Converting Complex Numbers. + (line 6) +* Copying conditions: Copying. (line 6) +* Installation: Installing GNU MPC. (line 6) +* Logarithm: Power Functions and Logarithm. + (line 6) +* Miscellaneous complex functions: Miscellaneous Complex Functions. + (line 6) +* 'mpc.h': GNU MPC Basics. (line 6) +* Power functions: Power Functions and Logarithm. + (line 6) +* Precision: GNU MPC Basics. (line 19) +* Projection and Decomposing Functions: Projection & Decomposing. + (line 6) +* Reporting bugs: Reporting Bugs. (line 6) +* Rounding Mode: GNU MPC Basics. (line 24) +* String and stream input and output: String and Stream Input and Output. + (line 6) +* Trigonometric functions: Trigonometric Functions. + (line 6) +* User-defined precision: Complex Functions. (line 12) + + +File: mpc.info, Node: Function Index, Next: GNU Free Documentation License, Prev: Concept Index, Up: Top + +Function Index +************** + + +* Menu: + +* _Complex: Converting Complex Numbers. + (line 9) +* mpc_abs: Basic Arithmetic. (line 81) +* mpc_acos: Trigonometric Functions. + (line 37) +* mpc_acosh: Trigonometric Functions. + (line 43) +* mpc_add: Basic Arithmetic. (line 11) +* mpc_add_fr: Basic Arithmetic. (line 15) +* mpc_add_ui: Basic Arithmetic. (line 13) +* mpc_arg: Projection & Decomposing. + (line 20) +* mpc_asin: Trigonometric Functions. + (line 36) +* mpc_asinh: Trigonometric Functions. + (line 42) +* mpc_atan: Trigonometric Functions. + (line 38) +* mpc_atanh: Trigonometric Functions. + (line 44) +* mpc_clear: Initializing Complex Numbers. + (line 21) +* mpc_cmp: Complex Comparison. (line 6) +* mpc_cmp_si: Complex Comparison. (line 9) +* mpc_cmp_si_si: Complex Comparison. (line 7) +* mpc_conj: Basic Arithmetic. (line 76) +* mpc_cos: Trigonometric Functions. + (line 10) +* mpc_cosh: Trigonometric Functions. + (line 28) +* mpc_div: Basic Arithmetic. (line 64) +* mpc_div_2si: Basic Arithmetic. (line 99) +* mpc_div_2ui: Basic Arithmetic. (line 97) +* mpc_div_fr: Basic Arithmetic. (line 68) +* mpc_div_ui: Basic Arithmetic. (line 66) +* mpc_exp: Power Functions and Logarithm. + (line 32) +* mpc_fma: Basic Arithmetic. (line 59) +* mpc_free_str: String and Stream Input and Output. + (line 66) +* mpc_fr_div: Basic Arithmetic. (line 72) +* mpc_fr_sub: Basic Arithmetic. (line 23) +* mpc_get_ldc: Converting Complex Numbers. + (line 10) +* mpc_get_prec: Initializing Complex Numbers. + (line 49) +* mpc_get_prec2: Initializing Complex Numbers. + (line 53) +* mpc_get_str: String and Stream Input and Output. + (line 48) +* mpc_get_version: Miscellaneous Complex Functions. + (line 14) +* mpc_imag: Projection & Decomposing. + (line 10) +* mpc_imagref: Projection & Decomposing. + (line 15) +* mpc_init2: Initializing Complex Numbers. + (line 10) +* mpc_init3: Initializing Complex Numbers. + (line 15) +* mpc_inp_str: String and Stream Input and Output. + (line 74) +* mpc_log: Power Functions and Logarithm. + (line 36) +* mpc_log10: Power Functions and Logarithm. + (line 37) +* mpc_mul: Basic Arithmetic. (line 38) +* mpc_mul_2si: Basic Arithmetic. (line 91) +* mpc_mul_2ui: Basic Arithmetic. (line 89) +* mpc_mul_fr: Basic Arithmetic. (line 44) +* mpc_mul_i: Basic Arithmetic. (line 50) +* mpc_mul_si: Basic Arithmetic. (line 42) +* mpc_mul_ui: Basic Arithmetic. (line 40) +* mpc_neg: Basic Arithmetic. (line 34) +* mpc_norm: Basic Arithmetic. (line 85) +* mpc_out_str: String and Stream Input and Output. + (line 109) +* mpc_pow: Power Functions and Logarithm. + (line 11) +* mpc_pow_d: Power Functions and Logarithm. + (line 13) +* mpc_pow_fr: Power Functions and Logarithm. + (line 23) +* mpc_pow_ld: Power Functions and Logarithm. + (line 15) +* mpc_pow_si: Power Functions and Logarithm. + (line 17) +* mpc_pow_ui: Power Functions and Logarithm. + (line 19) +* mpc_pow_z: Power Functions and Logarithm. + (line 21) +* mpc_proj: Projection & Decomposing. + (line 24) +* mpc_real: Projection & Decomposing. + (line 6) +* mpc_realref: Projection & Decomposing. + (line 14) +* 'mpc_rnd_t': GNU MPC Basics. (line 24) +* mpc_set: Assigning Complex Numbers. + (line 16) +* mpc_set_d: Assigning Complex Numbers. + (line 25) +* mpc_set_dc: Assigning Complex Numbers. + (line 27) +* mpc_set_d_d: Assigning Complex Numbers. + (line 54) +* mpc_set_f: Assigning Complex Numbers. + (line 33) +* mpc_set_fr: Assigning Complex Numbers. + (line 34) +* mpc_set_fr_fr: Assigning Complex Numbers. + (line 64) +* mpc_set_f_f: Assigning Complex Numbers. + (line 62) +* mpc_set_ld: Assigning Complex Numbers. + (line 26) +* mpc_set_ldc: Assigning Complex Numbers. + (line 29) +* mpc_set_ld_ld: Assigning Complex Numbers. + (line 56) +* mpc_set_nan: Assigning Complex Numbers. + (line 79) +* mpc_set_prec: Initializing Complex Numbers. + (line 41) +* mpc_set_q: Assigning Complex Numbers. + (line 32) +* mpc_set_q_q: Assigning Complex Numbers. + (line 60) +* mpc_set_si: Assigning Complex Numbers. + (line 22) +* mpc_set_si_si: Assigning Complex Numbers. + (line 48) +* mpc_set_sj: Assigning Complex Numbers. + (line 24) +* mpc_set_sj_sj: Assigning Complex Numbers. + (line 52) +* mpc_set_str: String and Stream Input and Output. + (line 35) +* mpc_set_ui: Assigning Complex Numbers. + (line 20) +* mpc_set_ui_ui: Assigning Complex Numbers. + (line 46) +* mpc_set_uj: Assigning Complex Numbers. + (line 23) +* mpc_set_uj_uj: Assigning Complex Numbers. + (line 50) +* MPC_SET_X_Y: Advanced Functions. (line 6) +* mpc_set_z: Assigning Complex Numbers. + (line 31) +* mpc_set_z_z: Assigning Complex Numbers. + (line 58) +* mpc_sin: Trigonometric Functions. + (line 6) +* mpc_sinh: Trigonometric Functions. + (line 24) +* mpc_sin_cos: Trigonometric Functions. + (line 14) +* mpc_sqr: Basic Arithmetic. (line 56) +* mpc_sqrt: Power Functions and Logarithm. + (line 6) +* mpc_strtoc: String and Stream Input and Output. + (line 6) +* mpc_sub: Basic Arithmetic. (line 19) +* mpc_sub_fr: Basic Arithmetic. (line 21) +* mpc_sub_ui: Basic Arithmetic. (line 25) +* mpc_swap: Assigning Complex Numbers. + (line 82) +* 'mpc_t': GNU MPC Basics. (line 15) +* mpc_tan: Trigonometric Functions. + (line 20) +* mpc_tanh: Trigonometric Functions. + (line 32) +* mpc_ui_div: Basic Arithmetic. (line 70) +* mpc_ui_sub: Basic Arithmetic. (line 27) +* mpc_ui_ui_sub: Basic Arithmetic. (line 29) +* mpc_urandom: Miscellaneous Complex Functions. + (line 6) +* MPC_VERSION: Miscellaneous Complex Functions. + (line 17) +* MPC_VERSION_MAJOR: Miscellaneous Complex Functions. + (line 18) +* MPC_VERSION_MINOR: Miscellaneous Complex Functions. + (line 19) +* MPC_VERSION_NUM: Miscellaneous Complex Functions. + (line 36) +* MPC_VERSION_PATCHLEVEL: Miscellaneous Complex Functions. + (line 20) +* MPC_VERSION_STRING: Miscellaneous Complex Functions. + (line 21) +* 'mpfr_prec_t': GNU MPC Basics. (line 19) + + +File: mpc.info, Node: GNU Free Documentation License, Prev: Function Index, Up: Top + +Appendix A GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + <http://fsf.org/> + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + <http://www.gnu.org/copyleft/>. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + + +Tag Table: +Node: Top736 +Node: Copying1443 +Node: Introduction to GNU MPC2215 +Node: Installing GNU MPC2934 +Node: Reporting Bugs8019 +Node: GNU MPC Basics9363 +Ref: return-value13040 +Node: Complex Functions14491 +Node: Initializing Complex Numbers15651 +Node: Assigning Complex Numbers18038 +Node: Converting Complex Numbers22438 +Node: String and Stream Input and Output23063 +Node: Complex Comparison29620 +Node: Projection & Decomposing30695 +Node: Basic Arithmetic32072 +Node: Power Functions and Logarithm36645 +Node: Trigonometric Functions38712 +Node: Miscellaneous Complex Functions40937 +Node: Advanced Functions43113 +Node: Internals44186 +Node: References44637 +Node: Concept Index45540 +Node: Function Index47854 +Node: GNU Free Documentation License61638 + +End Tag Table diff --git a/mpfr/doc/mpfr.info b/mpfr/doc/mpfr.info new file mode 100644 index 0000000000..fb90a4ae8e --- /dev/null +++ b/mpfr/doc/mpfr.info @@ -0,0 +1,4245 @@ +This is mpfr.info, produced by makeinfo version 5.2 from mpfr.texi. + +This manual documents how to install and use the Multiple Precision +Floating-Point Reliable Library, version 3.1.3. + + Copyright 1991, 1993-2015 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in *note GNU Free +Documentation License::. +INFO-DIR-SECTION Software libraries +START-INFO-DIR-ENTRY +* mpfr: (mpfr). Multiple Precision Floating-Point Reliable Library. +END-INFO-DIR-ENTRY + + +File: mpfr.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) + +GNU MPFR +******** + +This manual documents how to install and use the Multiple Precision +Floating-Point Reliable Library, version 3.1.3. + + Copyright 1991, 1993-2015 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in *note GNU Free +Documentation License::. + +* Menu: + +* Copying:: MPFR Copying Conditions (LGPL). +* Introduction to MPFR:: Brief introduction to GNU MPFR. +* Installing MPFR:: How to configure and compile the MPFR library. +* Reporting Bugs:: How to usefully report bugs. +* MPFR Basics:: What every MPFR user should now. +* MPFR Interface:: MPFR functions and macros. +* API Compatibility:: API compatibility with previous MPFR versions. +* Contributors:: +* References:: +* GNU Free Documentation License:: +* Concept Index:: +* Function and Type Index:: + + +File: mpfr.info, Node: Copying, Next: Introduction to MPFR, Prev: Top, Up: Top + +MPFR Copying Conditions +*********************** + +The GNU MPFR library (or MPFR for short) is "free"; this means that +everyone is free to use it and free to redistribute it on a free basis. +The library is not in the public domain; it is copyrighted and there are +restrictions on its distribution, but these restrictions are designed to +permit everything that a good cooperating citizen would want to do. +What is not allowed is to try to prevent others from further sharing any +version of this library that they might get from you. + + Specifically, we want to make sure that you have the right to give +away copies of the library, that you receive source code or else can get +it if you want it, that you can change this library or use pieces of it +in new free programs, and that you know you can do these things. + + To make sure that everyone has such rights, we have to forbid you to +deprive anyone else of these rights. For example, if you distribute +copies of the GNU MPFR library, you must give the recipients all the +rights that you have. You must make sure that they, too, receive or can +get the source code. And you must tell them their rights. + + Also, for our own protection, we must make certain that everyone +finds out that there is no warranty for the GNU MPFR library. If it is +modified by someone else and passed on, we want their recipients to know +that what they have is not what we distributed, so that any problems +introduced by others will not reflect on our reputation. + + The precise conditions of the license for the GNU MPFR library are +found in the Lesser General Public License that accompanies the source +code. See the file COPYING.LESSER. + + +File: mpfr.info, Node: Introduction to MPFR, Next: Installing MPFR, Prev: Copying, Up: Top + +1 Introduction to MPFR +********************** + +MPFR is a portable library written in C for arbitrary precision +arithmetic on floating-point numbers. It is based on the GNU MP +library. It aims to provide a class of floating-point numbers with +precise semantics. The main characteristics of MPFR, which make it +differ from most arbitrary precision floating-point software tools, are: + + • the MPFR code is portable, i.e., the result of any operation does + not depend on the machine word size ‘mp_bits_per_limb’ (64 on most + current processors); + + • the precision in bits can be set _exactly_ to any valid value for + each variable (including very small precision); + + • MPFR provides the four rounding modes from the IEEE 754-1985 + standard, plus away-from-zero, as well as for basic operations as + for other mathematical functions. + + In particular, with a precision of 53 bits, MPFR is able to exactly +reproduce all computations with double-precision machine floating-point +numbers (e.g., ‘double’ type in C, with a C implementation that +rigorously follows Annex F of the ISO C99 standard and ‘FP_CONTRACT’ +pragma set to ‘OFF’) on the four arithmetic operations and the square +root, except the default exponent range is much wider and subnormal +numbers are not implemented (but can be emulated). + + This version of MPFR is released under the GNU Lesser General Public +License, version 3 or any later version. It is permitted to link MPFR +to most non-free programs, as long as when distributing them the MPFR +source code and a means to re-link with a modified MPFR library is +provided. + +1.1 How to Use This Manual +========================== + +Everyone should read *note MPFR Basics::. If you need to install the +library yourself, you need to read *note Installing MPFR::, too. To use +the library you will need to refer to *note MPFR Interface::. + + The rest of the manual can be used for later reference, although it +is probably a good idea to glance through it. + + +File: mpfr.info, Node: Installing MPFR, Next: Reporting Bugs, Prev: Introduction to MPFR, Up: Top + +2 Installing MPFR +***************** + +The MPFR library is already installed on some GNU/Linux distributions, +but the development files necessary to the compilation such as ‘mpfr.h’ +are not always present. To check that MPFR is fully installed on your +computer, you can check the presence of the file ‘mpfr.h’ in +‘/usr/include’, or try to compile a small program having ‘#include +<mpfr.h>’ (since ‘mpfr.h’ may be installed somewhere else). For +instance, you can try to compile: + + #include <stdio.h> + #include <mpfr.h> + int main (void) + { + printf ("MPFR library: %-12s\nMPFR header: %s (based on %d.%d.%d)\n", + mpfr_get_version (), MPFR_VERSION_STRING, MPFR_VERSION_MAJOR, + MPFR_VERSION_MINOR, MPFR_VERSION_PATCHLEVEL); + return 0; + } + +with + + cc -o version version.c -lmpfr -lgmp + +and if you get errors whose first line looks like + + version.c:2:19: error: mpfr.h: No such file or directory + +then MPFR is probably not installed. Running this program will give you +the MPFR version. + + If MPFR is not installed on your computer, or if you want to install +a different version, please follow the steps below. + +2.1 How to Install +================== + +Here are the steps needed to install the library on Unix systems (more +details are provided in the ‘INSTALL’ file): + + 1. To build MPFR, you first have to install GNU MP (version 4.1 or + higher) on your computer. You need a C compiler, preferably GCC, + but any reasonable compiler should work. And you need the standard + Unix ‘make’ command, plus some other standard Unix utility + commands. + + Then, in the MPFR build directory, type the following commands. + + 2. ‘./configure’ + + This will prepare the build and setup the options according to your + system. You can give options to specify the install directories + (instead of the default ‘/usr/local’), threading support, and so + on. See the ‘INSTALL’ file and/or the output of ‘./configure + --help’ for more information, in particular if you get error + messages. + + 3. ‘make’ + + This will compile MPFR, and create a library archive file + ‘libmpfr.a’. On most platforms, a dynamic library will be produced + too. + + 4. ‘make check’ + + This will make sure that MPFR was built correctly. If any test + fails, information about this failure can be found in the + ‘tests/test-suite.log’ file. If you want the contents of this file + to be automatically output in case of failure, you can set the + ‘VERBOSE’ environment variable to 1 before running ‘make check’, + for instance by typing: + + ‘VERBOSE=1 make check’ + + In case of failure, you may want to check whether the problem is + already known. If not, please report this failure to the MPFR + mailing-list ‘mpfr@inria.fr’. For details, *Note Reporting Bugs::. + + 5. ‘make install’ + + This will copy the files ‘mpfr.h’ and ‘mpf2mpfr.h’ to the directory + ‘/usr/local/include’, the library files (‘libmpfr.a’ and possibly + others) to the directory ‘/usr/local/lib’, the file ‘mpfr.info’ to + the directory ‘/usr/local/share/info’, and some other documentation + files to the directory ‘/usr/local/share/doc/mpfr’ (or if you + passed the ‘--prefix’ option to ‘configure’, using the prefix + directory given as argument to ‘--prefix’ instead of ‘/usr/local’). + +2.2 Other ‘make’ Targets +======================== + +There are some other useful make targets: + + • ‘mpfr.info’ or ‘info’ + + Create or update an info version of the manual, in ‘mpfr.info’. + + This file is already provided in the MPFR archives. + + • ‘mpfr.pdf’ or ‘pdf’ + + Create a PDF version of the manual, in ‘mpfr.pdf’. + + • ‘mpfr.dvi’ or ‘dvi’ + + Create a DVI version of the manual, in ‘mpfr.dvi’. + + • ‘mpfr.ps’ or ‘ps’ + + Create a Postscript version of the manual, in ‘mpfr.ps’. + + • ‘mpfr.html’ or ‘html’ + + Create a HTML version of the manual, in several pages in the + directory ‘doc/mpfr.html’; if you want only one output HTML file, + then type ‘makeinfo --html --no-split mpfr.texi’ from the ‘doc’ + directory instead. + + • ‘clean’ + + Delete all object files and archive files, but not the + configuration files. + + • ‘distclean’ + + Delete all generated files not included in the distribution. + + • ‘uninstall’ + + Delete all files copied by ‘make install’. + +2.3 Build Problems +================== + +In case of problem, please read the ‘INSTALL’ file carefully before +reporting a bug, in particular section “In case of problem”. Some +problems are due to bad configuration on the user side (not specific to +MPFR). Problems are also mentioned in the FAQ +<http://www.mpfr.org/faq.html>. + + Please report problems to the MPFR mailing-list ‘mpfr@inria.fr’. +*Note Reporting Bugs::. Some bug fixes are available on the MPFR 3.1.3 +web page <http://www.mpfr.org/mpfr-3.1.3/>. + +2.4 Getting the Latest Version of MPFR +====================================== + +The latest version of MPFR is available from +<ftp://ftp.gnu.org/gnu/mpfr/> or <http://www.mpfr.org/>. + + +File: mpfr.info, Node: Reporting Bugs, Next: MPFR Basics, Prev: Installing MPFR, Up: Top + +3 Reporting Bugs +**************** + +If you think you have found a bug in the MPFR library, first have a look +on the MPFR 3.1.3 web page <http://www.mpfr.org/mpfr-3.1.3/> and the FAQ +<http://www.mpfr.org/faq.html>: perhaps this bug is already known, in +which case you may find there a workaround for it. You might also look +in the archives of the MPFR mailing-list: +<https://sympa.inria.fr/sympa/arc/mpfr>. Otherwise, please investigate +and report it. We have made this library available to you, and it is +not to ask too much from you, to ask you to report the bugs that you +find. + + There are a few things you should think about when you put your bug +report together. + + You have to send us a test case that makes it possible for us to +reproduce the bug, i.e., a small self-content program, using no other +library than MPFR. Include instructions on how to run the test case. + + You also have to explain what is wrong; if you get a crash, or if the +results you get are incorrect and in that case, in what way. + + Please include compiler version information in your bug report. This +can be extracted using ‘cc -V’ on some machines, or, if you’re using +GCC, ‘gcc -v’. Also, include the output from ‘uname -a’ and the MPFR +version (the GMP version may be useful too). If you get a failure while +running ‘make’ or ‘make check’, please include the ‘config.log’ file in +your bug report, and in case of test failure, the ‘tests/test-suite.log’ +file too. + + If your bug report is good, we will do our best to help you to get a +corrected version of the library; if the bug report is poor, we will not +do anything about it (aside of chiding you to send better bug reports). + + Send your bug report to the MPFR mailing-list ‘mpfr@inria.fr’. + + If you think something in this manual is unclear, or downright +incorrect, or if the language needs to be improved, please send a note +to the same address. + + +File: mpfr.info, Node: MPFR Basics, Next: MPFR Interface, Prev: Reporting Bugs, Up: Top + +4 MPFR Basics +************* + +* Menu: + +* Headers and Libraries:: +* Nomenclature and Types:: +* MPFR Variable Conventions:: +* Rounding Modes:: +* Floating-Point Values on Special Numbers:: +* Exceptions:: +* Memory Handling:: + + +File: mpfr.info, Node: Headers and Libraries, Next: Nomenclature and Types, Prev: MPFR Basics, Up: MPFR Basics + +4.1 Headers and Libraries +========================= + +All declarations needed to use MPFR are collected in the include file +‘mpfr.h’. It is designed to work with both C and C++ compilers. You +should include that file in any program using the MPFR library: + + #include <mpfr.h> + + Note however that prototypes for MPFR functions with ‘FILE *’ +parameters are provided only if ‘<stdio.h>’ is included too (before +‘mpfr.h’): + + #include <stdio.h> + #include <mpfr.h> + + Likewise ‘<stdarg.h>’ (or ‘<varargs.h>’) is required for prototypes +with ‘va_list’ parameters, such as ‘mpfr_vprintf’. + + And for any functions using ‘intmax_t’, you must include ‘<stdint.h>’ +or ‘<inttypes.h>’ before ‘mpfr.h’, to allow ‘mpfr.h’ to define +prototypes for these functions. Moreover, users of C++ compilers under +some platforms may need to define ‘MPFR_USE_INTMAX_T’ (and should do it +for portability) before ‘mpfr.h’ has been included; of course, it is +possible to do that on the command line, e.g., with +‘-DMPFR_USE_INTMAX_T’. + + Note: If ‘mpfr.h’ and/or ‘gmp.h’ (used by ‘mpfr.h’) are included +several times (possibly from another header file), ‘<stdio.h>’ and/or +‘<stdarg.h>’ (or ‘<varargs.h>’) should be included *before the first +inclusion* of ‘mpfr.h’ or ‘gmp.h’. Alternatively, you can define +‘MPFR_USE_FILE’ (for MPFR I/O functions) and/or ‘MPFR_USE_VA_LIST’ (for +MPFR functions with ‘va_list’ parameters) anywhere before the last +inclusion of ‘mpfr.h’. As a consequence, if your file is a public +header that includes ‘mpfr.h’, you need to use the latter method. + + When calling a MPFR macro, it is not allowed to have previously +defined a macro with the same name as some keywords (currently ‘do’, +‘while’ and ‘sizeof’). + + You can avoid the use of MPFR macros encapsulating functions by +defining the ‘MPFR_USE_NO_MACRO’ macro before ‘mpfr.h’ is included. In +general this should not be necessary, but this can be useful when +debugging user code: with some macros, the compiler may emit spurious +warnings with some warning options, and macros can prevent some +prototype checking. + + All programs using MPFR must link against both ‘libmpfr’ and ‘libgmp’ +libraries. On a typical Unix-like system this can be done with ‘-lmpfr +-lgmp’ (in that order), for example: + + gcc myprogram.c -lmpfr -lgmp + + MPFR is built using Libtool and an application can use that to link +if desired, *note GNU Libtool: (libtool.info)Top. + + If MPFR has been installed to a non-standard location, then it may be +necessary to set up environment variables such as ‘C_INCLUDE_PATH’ and +‘LIBRARY_PATH’, or use ‘-I’ and ‘-L’ compiler options, in order to point +to the right directories. For a shared library, it may also be +necessary to set up some sort of run-time library path (e.g., +‘LD_LIBRARY_PATH’) on some systems. Please read the ‘INSTALL’ file for +additional information. + + +File: mpfr.info, Node: Nomenclature and Types, Next: MPFR Variable Conventions, Prev: Headers and Libraries, Up: MPFR Basics + +4.2 Nomenclature and Types +========================== + +A "floating-point number", or "float" for short, is an arbitrary +precision significand (also called mantissa) with a limited precision +exponent. The C data type for such objects is ‘mpfr_t’ (internally +defined as a one-element array of a structure, and ‘mpfr_ptr’ is the C +data type representing a pointer to this structure). A floating-point +number can have three special values: Not-a-Number (NaN) or plus or +minus Infinity. NaN represents an uninitialized object, the result of +an invalid operation (like 0 divided by 0), or a value that cannot be +determined (like +Infinity minus +Infinity). Moreover, like in the IEEE +754 standard, zero is signed, i.e., there are both +0 and −0; the +behavior is the same as in the IEEE 754 standard and it is generalized +to the other functions supported by MPFR. Unless documented otherwise, +the sign bit of a NaN is unspecified. + +The "precision" is the number of bits used to represent the significand +of a floating-point number; the corresponding C data type is +‘mpfr_prec_t’. The precision can be any integer between ‘MPFR_PREC_MIN’ +and ‘MPFR_PREC_MAX’. In the current implementation, ‘MPFR_PREC_MIN’ is +equal to 2. + + Warning! MPFR needs to increase the precision internally, in order +to provide accurate results (and in particular, correct rounding). Do +not attempt to set the precision to any value near ‘MPFR_PREC_MAX’, +otherwise MPFR will abort due to an assertion failure. Moreover, you +may reach some memory limit on your platform, in which case the program +may abort, crash or have undefined behavior (depending on your C +implementation). + +The "rounding mode" specifies the way to round the result of a +floating-point operation, in case the exact result can not be +represented exactly in the destination significand; the corresponding C +data type is ‘mpfr_rnd_t’. + + +File: mpfr.info, Node: MPFR Variable Conventions, Next: Rounding Modes, Prev: Nomenclature and Types, Up: MPFR Basics + +4.3 MPFR Variable Conventions +============================= + +Before you can assign to an MPFR variable, you need to initialize it by +calling one of the special initialization functions. When you’re done +with a variable, you need to clear it out, using one of the functions +for that purpose. A variable should only be initialized once, or at +least cleared out between each initialization. After a variable has +been initialized, it may be assigned to any number of times. For +efficiency reasons, avoid to initialize and clear out a variable in +loops. Instead, initialize it before entering the loop, and clear it +out after the loop has exited. You do not need to be concerned about +allocating additional space for MPFR variables, since any variable has a +significand of fixed size. Hence unless you change its precision, or +clear and reinitialize it, a floating-point variable will have the same +allocated space during all its life. + + As a general rule, all MPFR functions expect output arguments before +input arguments. This notation is based on an analogy with the +assignment operator. MPFR allows you to use the same variable for both +input and output in the same expression. For example, the main function +for floating-point multiplication, ‘mpfr_mul’, can be used like this: +‘mpfr_mul (x, x, x, rnd)’. This computes the square of X with rounding +mode ‘rnd’ and puts the result back in X. + + +File: mpfr.info, Node: Rounding Modes, Next: Floating-Point Values on Special Numbers, Prev: MPFR Variable Conventions, Up: MPFR Basics + +4.4 Rounding Modes +================== + +The following five rounding modes are supported: + • ‘MPFR_RNDN’: round to nearest (roundTiesToEven in IEEE 754-2008), + • ‘MPFR_RNDZ’: round toward zero (roundTowardZero in IEEE 754-2008), + • ‘MPFR_RNDU’: round toward plus infinity (roundTowardPositive in + IEEE 754-2008), + • ‘MPFR_RNDD’: round toward minus infinity (roundTowardNegative in + IEEE 754-2008), + • ‘MPFR_RNDA’: round away from zero. + + The ‘round to nearest’ mode works as in the IEEE 754 standard: in +case the number to be rounded lies exactly in the middle of two +representable numbers, it is rounded to the one with the least +significant bit set to zero. For example, the number 2.5, which is +represented by (10.1) in binary, is rounded to (10.0)=2 with a precision +of two bits, and not to (11.0)=3. This rule avoids the "drift" +phenomenon mentioned by Knuth in volume 2 of The Art of Computer +Programming (Section 4.2.2). + + Most MPFR functions take as first argument the destination variable, +as second and following arguments the input variables, as last argument +a rounding mode, and have a return value of type ‘int’, called the +"ternary value". The value stored in the destination variable is +correctly rounded, i.e., MPFR behaves as if it computed the result with +an infinite precision, then rounded it to the precision of this +variable. The input variables are regarded as exact (in particular, +their precision does not affect the result). + + As a consequence, in case of a non-zero real rounded result, the +error on the result is less or equal to 1/2 ulp (unit in the last place) +of that result in the rounding to nearest mode, and less than 1 ulp of +that result in the directed rounding modes (a ulp is the weight of the +least significant represented bit of the result after rounding). + + Unless documented otherwise, functions returning an ‘int’ return a +ternary value. If the ternary value is zero, it means that the value +stored in the destination variable is the exact result of the +corresponding mathematical function. If the ternary value is positive +(resp. negative), it means the value stored in the destination variable +is greater (resp. lower) than the exact result. For example with the +‘MPFR_RNDU’ rounding mode, the ternary value is usually positive, except +when the result is exact, in which case it is zero. In the case of an +infinite result, it is considered as inexact when it was obtained by +overflow, and exact otherwise. A NaN result (Not-a-Number) always +corresponds to an exact return value. The opposite of a returned +ternary value is guaranteed to be representable in an ‘int’. + + Unless documented otherwise, functions returning as result the value +‘1’ (or any other value specified in this manual) for special cases +(like ‘acos(0)’) yield an overflow or an underflow if that value is not +representable in the current exponent range. + + +File: mpfr.info, Node: Floating-Point Values on Special Numbers, Next: Exceptions, Prev: Rounding Modes, Up: MPFR Basics + +4.5 Floating-Point Values on Special Numbers +============================================ + +This section specifies the floating-point values (of type ‘mpfr_t’) +returned by MPFR functions (where by “returned” we mean here the +modified value of the destination object, which should not be mixed with +the ternary return value of type ‘int’ of those functions). For +functions returning several values (like ‘mpfr_sin_cos’), the rules +apply to each result separately. + + Functions can have one or several input arguments. An input point is +a mapping from these input arguments to the set of the MPFR numbers. +When none of its components are NaN, an input point can also be seen as +a tuple in the extended real numbers (the set of the real numbers with +both infinities). + + When the input point is in the domain of the mathematical function, +the result is rounded as described in Section “Rounding Modes” (but see +below for the specification of the sign of an exact zero). Otherwise +the general rules from this section apply unless stated otherwise in the +description of the MPFR function (*note MPFR Interface::). + + When the input point is not in the domain of the mathematical +function but is in its closure in the extended real numbers and the +function can be extended by continuity, the result is the obtained +limit. Examples: ‘mpfr_hypot’ on (+Inf,0) gives +Inf. But ‘mpfr_pow’ +cannot be defined on (1,+Inf) using this rule, as one can find sequences +(X_N,Y_N) such that X_N goes to 1, Y_N goes to +Inf and X_N to the Y_N +goes to any positive value when N goes to the infinity. + + When the input point is in the closure of the domain of the +mathematical function and an input argument is +0 (resp. −0), one +considers the limit when the corresponding argument approaches 0 from +above (resp. below). If the limit is not defined (e.g., ‘mpfr_log’ on +−0), the behavior is specified in the description of the MPFR function. + + When the result is equal to 0, its sign is determined by considering +the limit as if the input point were not in the domain: If one +approaches 0 from above (resp. below), the result is +0 (resp. −0); for +example, ‘mpfr_sin’ on +0 gives +0. In the other cases, the sign is +specified in the description of the MPFR function; for example +‘mpfr_max’ on −0 and +0 gives +0. + + When the input point is not in the closure of the domain of the +function, the result is NaN. Example: ‘mpfr_sqrt’ on −17 gives NaN. + + When an input argument is NaN, the result is NaN, possibly except +when a partial function is constant on the finite floating-point +numbers; such a case is always explicitly specified in *note MPFR +Interface::. Example: ‘mpfr_hypot’ on (NaN,0) gives NaN, but +‘mpfr_hypot’ on (NaN,+Inf) gives +Inf (as specified in *note Special +Functions::), since for any finite input X, ‘mpfr_hypot’ on (X,+Inf) +gives +Inf. + + +File: mpfr.info, Node: Exceptions, Next: Memory Handling, Prev: Floating-Point Values on Special Numbers, Up: MPFR Basics + +4.6 Exceptions +============== + +MPFR supports 6 exception types: + + • Underflow: An underflow occurs when the exact result of a function + is a non-zero real number and the result obtained after the + rounding, assuming an unbounded exponent range (for the rounding), + has an exponent smaller than the minimum value of the current + exponent range. (In the round-to-nearest mode, the halfway case is + rounded toward zero.) + + Note: This is not the single possible definition of the underflow. + MPFR chooses to consider the underflow _after_ rounding. The + underflow before rounding can also be defined. For instance, + consider a function that has the exact result 7 multiplied by two + to the power E−4, where E is the smallest exponent (for a + significand between 1/2 and 1), with a 2-bit target precision and + rounding toward plus infinity. The exact result has the exponent + E−1. With the underflow before rounding, such a function call + would yield an underflow, as E−1 is outside the current exponent + range. However, MPFR first considers the rounded result assuming + an unbounded exponent range. The exact result cannot be + represented exactly in precision 2, and here, it is rounded to 0.5 + times 2 to E, which is representable in the current exponent range. + As a consequence, this will not yield an underflow in MPFR. + + • Overflow: An overflow occurs when the exact result of a function is + a non-zero real number and the result obtained after the rounding, + assuming an unbounded exponent range (for the rounding), has an + exponent larger than the maximum value of the current exponent + range. In the round-to-nearest mode, the result is infinite. + Note: unlike the underflow case, there is only one possible + definition of overflow here. + + • Divide-by-zero: An exact infinite result is obtained from finite + inputs. + + • NaN: A NaN exception occurs when the result of a function is NaN. + + • Inexact: An inexact exception occurs when the result of a function + cannot be represented exactly and must be rounded. + + • Range error: A range exception occurs when a function that does not + return a MPFR number (such as comparisons and conversions to an + integer) has an invalid result (e.g., an argument is NaN in + ‘mpfr_cmp’, or a conversion to an integer cannot be represented in + the target type). + + MPFR has a global flag for each exception, which can be cleared, set +or tested by functions described in *note Exception Related Functions::. + + Differences with the ISO C99 standard: + + • In C, only quiet NaNs are specified, and a NaN propagation does not + raise an invalid exception. Unless explicitly stated otherwise, + MPFR sets the NaN flag whenever a NaN is generated, even when a NaN + is propagated (e.g., in NaN + NaN), as if all NaNs were signaling. + + • An invalid exception in C corresponds to either a NaN exception or + a range error in MPFR. + + +File: mpfr.info, Node: Memory Handling, Prev: Exceptions, Up: MPFR Basics + +4.7 Memory Handling +=================== + +MPFR functions may create caches, e.g., when computing constants such as +Pi, either because the user has called a function like ‘mpfr_const_pi’ +directly or because such a function was called internally by the MPFR +library itself to compute some other function. + + At any time, the user can free the various caches with +‘mpfr_free_cache’. It is strongly advised to do that before terminating +a thread, or before exiting when using tools like ‘valgrind’ (to avoid +memory leaks being reported). + + MPFR internal data such as flags, the exponent range, the default +precision and rounding mode, and caches (i.e., data that are not +accessed via parameters) are either global (if MPFR has not been +compiled as thread safe) or per-thread (thread local storage, TLS). The +initial values of TLS data after a thread is created entirely depend on +the compiler and thread implementation (MPFR simply does a conventional +variable initialization, the variables being declared with an +implementation-defined TLS specifier). + + +File: mpfr.info, Node: MPFR Interface, Next: API Compatibility, Prev: MPFR Basics, Up: Top + +5 MPFR Interface +**************** + +The floating-point functions expect arguments of type ‘mpfr_t’. + + The MPFR floating-point functions have an interface that is similar +to the GNU MP functions. The function prefix for floating-point +operations is ‘mpfr_’. + + The user has to specify the precision of each variable. A +computation that assigns a variable will take place with the precision +of the assigned variable; the cost of that computation should not depend +on the precision of variables used as input (on average). + + The semantics of a calculation in MPFR is specified as follows: +Compute the requested operation exactly (with “infinite accuracy”), and +round the result to the precision of the destination variable, with the +given rounding mode. The MPFR floating-point functions are intended to +be a smooth extension of the IEEE 754 arithmetic. The results obtained +on a given computer are identical to those obtained on a computer with a +different word size, or with a different compiler or operating system. + + MPFR _does not keep track_ of the accuracy of a computation. This is +left to the user or to a higher layer (for example the MPFI library for +interval arithmetic). As a consequence, if two variables are used to +store only a few significant bits, and their product is stored in a +variable with large precision, then MPFR will still compute the result +with full precision. + + The value of the standard C macro ‘errno’ may be set to non-zero by +any MPFR function or macro, whether or not there is an error. + +* Menu: + +* Initialization Functions:: +* Assignment Functions:: +* Combined Initialization and Assignment Functions:: +* Conversion Functions:: +* Basic Arithmetic Functions:: +* Comparison Functions:: +* Special Functions:: +* Input and Output Functions:: +* Formatted Output Functions:: +* Integer Related Functions:: +* Rounding Related Functions:: +* Miscellaneous Functions:: +* Exception Related Functions:: +* Compatibility with MPF:: +* Custom Interface:: +* Internals:: + + +File: mpfr.info, Node: Initialization Functions, Next: Assignment Functions, Prev: MPFR Interface, Up: MPFR Interface + +5.1 Initialization Functions +============================ + +An ‘mpfr_t’ object must be initialized before storing the first value in +it. The functions ‘mpfr_init’ and ‘mpfr_init2’ are used for that +purpose. + + -- Function: void mpfr_init2 (mpfr_t X, mpfr_prec_t PREC) + Initialize X, set its precision to be *exactly* PREC bits and its + value to NaN. (Warning: the corresponding MPF function initializes + to zero instead.) + + Normally, a variable should be initialized once only or at least be + cleared, using ‘mpfr_clear’, between initializations. To change + the precision of a variable which has already been initialized, use + ‘mpfr_set_prec’. The precision PREC must be an integer between + ‘MPFR_PREC_MIN’ and ‘MPFR_PREC_MAX’ (otherwise the behavior is + undefined). + + -- Function: void mpfr_inits2 (mpfr_prec_t PREC, mpfr_t X, ...) + Initialize all the ‘mpfr_t’ variables of the given variable + argument ‘va_list’, set their precision to be *exactly* PREC bits + and their value to NaN. See ‘mpfr_init2’ for more details. The + ‘va_list’ is assumed to be composed only of type ‘mpfr_t’ (or + equivalently ‘mpfr_ptr’). It begins from X, and ends when it + encounters a null pointer (whose type must also be ‘mpfr_ptr’). + + -- Function: void mpfr_clear (mpfr_t X) + Free the space occupied by the significand of X. Make sure to call + this function for all ‘mpfr_t’ variables when you are done with + them. + + -- Function: void mpfr_clears (mpfr_t X, ...) + Free the space occupied by all the ‘mpfr_t’ variables of the given + ‘va_list’. See ‘mpfr_clear’ for more details. The ‘va_list’ is + assumed to be composed only of type ‘mpfr_t’ (or equivalently + ‘mpfr_ptr’). It begins from X, and ends when it encounters a null + pointer (whose type must also be ‘mpfr_ptr’). + + Here is an example of how to use multiple initialization functions +(since ‘NULL’ is not necessarily defined in this context, we use +‘(mpfr_ptr) 0’ instead, but ‘(mpfr_ptr) NULL’ is also correct). + + { + mpfr_t x, y, z, t; + mpfr_inits2 (256, x, y, z, t, (mpfr_ptr) 0); + … + mpfr_clears (x, y, z, t, (mpfr_ptr) 0); + } + + -- Function: void mpfr_init (mpfr_t X) + Initialize X, set its precision to the default precision, and set + its value to NaN. The default precision can be changed by a call to + ‘mpfr_set_default_prec’. + + Warning! In a given program, some other libraries might change the + default precision and not restore it. Thus it is safer to use + ‘mpfr_init2’. + + -- Function: void mpfr_inits (mpfr_t X, ...) + Initialize all the ‘mpfr_t’ variables of the given ‘va_list’, set + their precision to the default precision and their value to NaN. + See ‘mpfr_init’ for more details. The ‘va_list’ is assumed to be + composed only of type ‘mpfr_t’ (or equivalently ‘mpfr_ptr’). It + begins from X, and ends when it encounters a null pointer (whose + type must also be ‘mpfr_ptr’). + + Warning! In a given program, some other libraries might change the + default precision and not restore it. Thus it is safer to use + ‘mpfr_inits2’. + + -- Macro: MPFR_DECL_INIT (NAME, PREC) + This macro declares NAME as an automatic variable of type ‘mpfr_t’, + initializes it and sets its precision to be *exactly* PREC bits and + its value to NaN. NAME must be a valid identifier. You must use + this macro in the declaration section. This macro is much faster + than using ‘mpfr_init2’ but has some drawbacks: + + • You *must not* call ‘mpfr_clear’ with variables created with + this macro (the storage is allocated at the point of + declaration and deallocated when the brace-level is exited). + + • You *cannot* change their precision. + + • You *should not* create variables with huge precision with + this macro. + + • Your compiler must support ‘Non-Constant Initializers’ + (standard in C++ and ISO C99) and ‘Token Pasting’ (standard in + ISO C89). If PREC is not a constant expression, your compiler + must support ‘variable-length automatic arrays’ (standard in + ISO C99). GCC 2.95.3 and above supports all these features. + If you compile your program with GCC in C89 mode and with + ‘-pedantic’, you may want to define the ‘MPFR_USE_EXTENSION’ + macro to avoid warnings due to the ‘MPFR_DECL_INIT’ + implementation. + + -- Function: void mpfr_set_default_prec (mpfr_prec_t PREC) + Set the default precision to be *exactly* PREC bits, where PREC can + be any integer between ‘MPFR_PREC_MIN’ and ‘MPFR_PREC_MAX’. The + precision of a variable means the number of bits used to store its + significand. All subsequent calls to ‘mpfr_init’ or ‘mpfr_inits’ + will use this precision, but previously initialized variables are + unaffected. The default precision is set to 53 bits initially. + + Note: when MPFR is built with the ‘--enable-thread-safe’ configure + option, the default precision is local to each thread. *Note + Memory Handling::, for more information. + + -- Function: mpfr_prec_t mpfr_get_default_prec (void) + Return the current default MPFR precision in bits. See the + documentation of ‘mpfr_set_default_prec’. + + Here is an example on how to initialize floating-point variables: + + { + mpfr_t x, y; + mpfr_init (x); /* use default precision */ + mpfr_init2 (y, 256); /* precision _exactly_ 256 bits */ + … + /* When the program is about to exit, do ... */ + mpfr_clear (x); + mpfr_clear (y); + mpfr_free_cache (); /* free the cache for constants like pi */ + } + + The following functions are useful for changing the precision during +a calculation. A typical use would be for adjusting the precision +gradually in iterative algorithms like Newton-Raphson, making the +computation precision closely match the actual accurate part of the +numbers. + + -- Function: void mpfr_set_prec (mpfr_t X, mpfr_prec_t PREC) + Reset the precision of X to be *exactly* PREC bits, and set its + value to NaN. The previous value stored in X is lost. It is + equivalent to a call to ‘mpfr_clear(x)’ followed by a call to + ‘mpfr_init2(x, prec)’, but more efficient as no allocation is done + in case the current allocated space for the significand of X is + enough. The precision PREC can be any integer between + ‘MPFR_PREC_MIN’ and ‘MPFR_PREC_MAX’. In case you want to keep the + previous value stored in X, use ‘mpfr_prec_round’ instead. + + Warning! You must not use this function if X was initialized with + ‘MPFR_DECL_INIT’ or with ‘mpfr_custom_init_set’ (*note Custom + Interface::). + + -- Function: mpfr_prec_t mpfr_get_prec (mpfr_t X) + Return the precision of X, i.e., the number of bits used to store + its significand. + + +File: mpfr.info, Node: Assignment Functions, Next: Combined Initialization and Assignment Functions, Prev: Initialization Functions, Up: MPFR Interface + +5.2 Assignment Functions +======================== + +These functions assign new values to already initialized floats (*note +Initialization Functions::). + + -- Function: int mpfr_set (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_set_ui (mpfr_t ROP, unsigned long int OP, + mpfr_rnd_t RND) + -- Function: int mpfr_set_si (mpfr_t ROP, long int OP, mpfr_rnd_t RND) + -- Function: int mpfr_set_uj (mpfr_t ROP, uintmax_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_set_sj (mpfr_t ROP, intmax_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_set_flt (mpfr_t ROP, float OP, mpfr_rnd_t RND) + -- Function: int mpfr_set_d (mpfr_t ROP, double OP, mpfr_rnd_t RND) + -- Function: int mpfr_set_ld (mpfr_t ROP, long double OP, mpfr_rnd_t + RND) + -- Function: int mpfr_set_decimal64 (mpfr_t ROP, _Decimal64 OP, + mpfr_rnd_t RND) + -- Function: int mpfr_set_z (mpfr_t ROP, mpz_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_set_q (mpfr_t ROP, mpq_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_set_f (mpfr_t ROP, mpf_t OP, mpfr_rnd_t RND) + Set the value of ROP from OP, rounded toward the given direction + RND. Note that the input 0 is converted to +0 by ‘mpfr_set_ui’, + ‘mpfr_set_si’, ‘mpfr_set_uj’, ‘mpfr_set_sj’, ‘mpfr_set_z’, + ‘mpfr_set_q’ and ‘mpfr_set_f’, regardless of the rounding mode. If + the system does not support the IEEE 754 standard, ‘mpfr_set_flt’, + ‘mpfr_set_d’, ‘mpfr_set_ld’ and ‘mpfr_set_decimal64’ might not + preserve the signed zeros. The ‘mpfr_set_decimal64’ function is + built only with the configure option ‘--enable-decimal-float’, + which also requires ‘--with-gmp-build’, and when the compiler or + system provides the ‘_Decimal64’ data type (recent versions of GCC + support this data type); to use ‘mpfr_set_decimal64’, one should + define the macro ‘MPFR_WANT_DECIMAL_FLOATS’ before including + ‘mpfr.h’. ‘mpfr_set_q’ might fail if the numerator (or the + denominator) can not be represented as a ‘mpfr_t’. + + Note: If you want to store a floating-point constant to a ‘mpfr_t’, + you should use ‘mpfr_set_str’ (or one of the MPFR constant + functions, such as ‘mpfr_const_pi’ for Pi) instead of + ‘mpfr_set_flt’, ‘mpfr_set_d’, ‘mpfr_set_ld’ or + ‘mpfr_set_decimal64’. Otherwise the floating-point constant will + be first converted into a reduced-precision (e.g., 53-bit) binary + (or decimal, for ‘mpfr_set_decimal64’) number before MPFR can work + with it. + + -- Function: int mpfr_set_ui_2exp (mpfr_t ROP, unsigned long int OP, + mpfr_exp_t E, mpfr_rnd_t RND) + -- Function: int mpfr_set_si_2exp (mpfr_t ROP, long int OP, mpfr_exp_t + E, mpfr_rnd_t RND) + -- Function: int mpfr_set_uj_2exp (mpfr_t ROP, uintmax_t OP, intmax_t + E, mpfr_rnd_t RND) + -- Function: int mpfr_set_sj_2exp (mpfr_t ROP, intmax_t OP, intmax_t E, + mpfr_rnd_t RND) + -- Function: int mpfr_set_z_2exp (mpfr_t ROP, mpz_t OP, mpfr_exp_t E, + mpfr_rnd_t RND) + Set the value of ROP from OP multiplied by two to the power E, + rounded toward the given direction RND. Note that the input 0 is + converted to +0. + + -- Function: int mpfr_set_str (mpfr_t ROP, const char *S, int BASE, + mpfr_rnd_t RND) + Set ROP to the value of the string S in base BASE, rounded in the + direction RND. See the documentation of ‘mpfr_strtofr’ for a + detailed description of the valid string formats. Contrary to + ‘mpfr_strtofr’, ‘mpfr_set_str’ requires the _whole_ string to + represent a valid floating-point number. + + The meaning of the return value differs from other MPFR functions: + it is 0 if the entire string up to the final null character is a + valid number in base BASE; otherwise it is −1, and ROP may have + changed (users interested in the *note ternary value:: should use + ‘mpfr_strtofr’ instead). + + Note: it is preferable to use ‘mpfr_strtofr’ if one wants to + distinguish between an infinite ROP value coming from an infinite S + or from an overflow. + + -- Function: int mpfr_strtofr (mpfr_t ROP, const char *NPTR, char + **ENDPTR, int BASE, mpfr_rnd_t RND) + Read a floating-point number from a string NPTR in base BASE, + rounded in the direction RND; BASE must be either 0 (to detect the + base, as described below) or a number from 2 to 62 (otherwise the + behavior is undefined). If NPTR starts with valid data, the result + is stored in ROP and ‘*ENDPTR’ points to the character just after + the valid data (if ENDPTR is not a null pointer); otherwise ROP is + set to zero (for consistency with ‘strtod’) and the value of NPTR + is stored in the location referenced by ENDPTR (if ENDPTR is not a + null pointer). The usual ternary value is returned. + + Parsing follows the standard C ‘strtod’ function with some + extensions. After optional leading whitespace, one has a subject + sequence consisting of an optional sign (‘+’ or ‘-’), and either + numeric data or special data. The subject sequence is defined as + the longest initial subsequence of the input string, starting with + the first non-whitespace character, that is of the expected form. + + The form of numeric data is a non-empty sequence of significand + digits with an optional decimal point, and an optional exponent + consisting of an exponent prefix followed by an optional sign and a + non-empty sequence of decimal digits. A significand digit is + either a decimal digit or a Latin letter (62 possible characters), + with ‘A’ = 10, ‘B’ = 11, …, ‘Z’ = 35; case is ignored in bases less + or equal to 36, in bases larger than 36, ‘a’ = 36, ‘b’ = 37, …, ‘z’ + = 61. The value of a significand digit must be strictly less than + the base. The decimal point can be either the one defined by the + current locale or the period (the first one is accepted for + consistency with the C standard and the practice, the second one is + accepted to allow the programmer to provide MPFR numbers from + strings in a way that does not depend on the current locale). The + exponent prefix can be ‘e’ or ‘E’ for bases up to 10, or ‘@’ in any + base; it indicates a multiplication by a power of the base. In + bases 2 and 16, the exponent prefix can also be ‘p’ or ‘P’, in + which case the exponent, called _binary exponent_, indicates a + multiplication by a power of 2 instead of the base (there is a + difference only for base 16); in base 16 for example ‘1p2’ + represents 4 whereas ‘1@2’ represents 256. The value of an + exponent is always written in base 10. + + If the argument BASE is 0, then the base is automatically detected + as follows. If the significand starts with ‘0b’ or ‘0B’, base 2 is + assumed. If the significand starts with ‘0x’ or ‘0X’, base 16 is + assumed. Otherwise base 10 is assumed. + + Note: The exponent (if present) must contain at least a digit. + Otherwise the possible exponent prefix and sign are not part of the + number (which ends with the significand). Similarly, if ‘0b’, + ‘0B’, ‘0x’ or ‘0X’ is not followed by a binary/hexadecimal digit, + then the subject sequence stops at the character ‘0’, thus 0 is + read. + + Special data (for infinities and NaN) can be ‘@inf@’ or + ‘@nan@(n-char-sequence-opt)’, and if BASE <= 16, it can also be + ‘infinity’, ‘inf’, ‘nan’ or ‘nan(n-char-sequence-opt)’, all case + insensitive. A ‘n-char-sequence-opt’ is a possibly empty string + containing only digits, Latin letters and the underscore (0, 1, 2, + …, 9, a, b, …, z, A, B, …, Z, _). Note: one has an optional sign + for all data, even NaN. For example, ‘-@nAn@(This_Is_Not_17)’ is a + valid representation for NaN in base 17. + + -- Function: void mpfr_set_nan (mpfr_t X) + -- Function: void mpfr_set_inf (mpfr_t X, int SIGN) + -- Function: void mpfr_set_zero (mpfr_t X, int SIGN) + Set the variable X to NaN (Not-a-Number), infinity or zero + respectively. In ‘mpfr_set_inf’ or ‘mpfr_set_zero’, X is set to + plus infinity or plus zero iff SIGN is nonnegative; in + ‘mpfr_set_nan’, the sign bit of the result is unspecified. + + -- Function: void mpfr_swap (mpfr_t X, mpfr_t Y) + Swap the structures pointed to by X and Y. In particular, the + values are exchanged without rounding (this may be different from + three ‘mpfr_set’ calls using a third auxiliary variable). + + Warning! Since the precisions are exchanged, this will affect + future assignments. Moreover, since the significand pointers are + also exchanged, you must not use this function if the allocation + method used for X and/or Y does not permit it. This is the case + when X and/or Y were declared and initialized with + ‘MPFR_DECL_INIT’, and possibly with ‘mpfr_custom_init_set’ (*note + Custom Interface::). + + +File: mpfr.info, Node: Combined Initialization and Assignment Functions, Next: Conversion Functions, Prev: Assignment Functions, Up: MPFR Interface + +5.3 Combined Initialization and Assignment Functions +==================================================== + + -- Macro: int mpfr_init_set (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Macro: int mpfr_init_set_ui (mpfr_t ROP, unsigned long int OP, + mpfr_rnd_t RND) + -- Macro: int mpfr_init_set_si (mpfr_t ROP, long int OP, mpfr_rnd_t + RND) + -- Macro: int mpfr_init_set_d (mpfr_t ROP, double OP, mpfr_rnd_t RND) + -- Macro: int mpfr_init_set_ld (mpfr_t ROP, long double OP, mpfr_rnd_t + RND) + -- Macro: int mpfr_init_set_z (mpfr_t ROP, mpz_t OP, mpfr_rnd_t RND) + -- Macro: int mpfr_init_set_q (mpfr_t ROP, mpq_t OP, mpfr_rnd_t RND) + -- Macro: int mpfr_init_set_f (mpfr_t ROP, mpf_t OP, mpfr_rnd_t RND) + Initialize ROP and set its value from OP, rounded in the direction + RND. The precision of ROP will be taken from the active default + precision, as set by ‘mpfr_set_default_prec’. + + -- Function: int mpfr_init_set_str (mpfr_t X, const char *S, int BASE, + mpfr_rnd_t RND) + Initialize X and set its value from the string S in base BASE, + rounded in the direction RND. See ‘mpfr_set_str’. + + +File: mpfr.info, Node: Conversion Functions, Next: Basic Arithmetic Functions, Prev: Combined Initialization and Assignment Functions, Up: MPFR Interface + +5.4 Conversion Functions +======================== + + -- Function: float mpfr_get_flt (mpfr_t OP, mpfr_rnd_t RND) + -- Function: double mpfr_get_d (mpfr_t OP, mpfr_rnd_t RND) + -- Function: long double mpfr_get_ld (mpfr_t OP, mpfr_rnd_t RND) + -- Function: _Decimal64 mpfr_get_decimal64 (mpfr_t OP, mpfr_rnd_t RND) + Convert OP to a ‘float’ (respectively ‘double’, ‘long double’ or + ‘_Decimal64’), using the rounding mode RND. If OP is NaN, some + fixed NaN (either quiet or signaling) or the result of 0.0/0.0 is + returned. If OP is ±Inf, an infinity of the same sign or the + result of ±1.0/0.0 is returned. If OP is zero, these functions + return a zero, trying to preserve its sign, if possible. The + ‘mpfr_get_decimal64’ function is built only under some conditions: + see the documentation of ‘mpfr_set_decimal64’. + + -- Function: long mpfr_get_si (mpfr_t OP, mpfr_rnd_t RND) + -- Function: unsigned long mpfr_get_ui (mpfr_t OP, mpfr_rnd_t RND) + -- Function: intmax_t mpfr_get_sj (mpfr_t OP, mpfr_rnd_t RND) + -- Function: uintmax_t mpfr_get_uj (mpfr_t OP, mpfr_rnd_t RND) + Convert OP to a ‘long’, an ‘unsigned long’, an ‘intmax_t’ or an + ‘uintmax_t’ (respectively) after rounding it with respect to RND. + If OP is NaN, 0 is returned and the _erange_ flag is set. If OP is + too big for the return type, the function returns the maximum or + the minimum of the corresponding C type, depending on the direction + of the overflow; the _erange_ flag is set too. See also + ‘mpfr_fits_slong_p’, ‘mpfr_fits_ulong_p’, ‘mpfr_fits_intmax_p’ and + ‘mpfr_fits_uintmax_p’. + + -- Function: double mpfr_get_d_2exp (long *EXP, mpfr_t OP, mpfr_rnd_t + RND) + -- Function: long double mpfr_get_ld_2exp (long *EXP, mpfr_t OP, + mpfr_rnd_t RND) + Return D and set EXP (formally, the value pointed to by EXP) such + that 0.5<=abs(D)<1 and D times 2 raised to EXP equals OP rounded to + double (resp. long double) precision, using the given rounding + mode. If OP is zero, then a zero of the same sign (or an unsigned + zero, if the implementation does not have signed zeros) is + returned, and EXP is set to 0. If OP is NaN or an infinity, then + the corresponding double precision (resp. long-double precision) + value is returned, and EXP is undefined. + + -- Function: int mpfr_frexp (mpfr_exp_t *EXP, mpfr_t Y, mpfr_t X, + mpfr_rnd_t RND) + Set EXP (formally, the value pointed to by EXP) and Y such that + 0.5<=abs(Y)<1 and Y times 2 raised to EXP equals X rounded to the + precision of Y, using the given rounding mode. If X is zero, then + Y is set to a zero of the same sign and EXP is set to 0. If X is + NaN or an infinity, then Y is set to the same value and EXP is + undefined. + + -- Function: mpfr_exp_t mpfr_get_z_2exp (mpz_t ROP, mpfr_t OP) + Put the scaled significand of OP (regarded as an integer, with the + precision of OP) into ROP, and return the exponent EXP (which may + be outside the current exponent range) such that OP exactly equals + ROP times 2 raised to the power EXP. If OP is zero, the minimal + exponent ‘emin’ is returned. If OP is NaN or an infinity, the + _erange_ flag is set, ROP is set to 0, and the the minimal exponent + ‘emin’ is returned. The returned exponent may be less than the + minimal exponent ‘emin’ of MPFR numbers in the current exponent + range; in case the exponent is not representable in the + ‘mpfr_exp_t’ type, the _erange_ flag is set and the minimal value + of the ‘mpfr_exp_t’ type is returned. + + -- Function: int mpfr_get_z (mpz_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Convert OP to a ‘mpz_t’, after rounding it with respect to RND. If + OP is NaN or an infinity, the _erange_ flag is set, ROP is set to + 0, and 0 is returned. + + -- Function: int mpfr_get_f (mpf_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Convert OP to a ‘mpf_t’, after rounding it with respect to RND. + The _erange_ flag is set if OP is NaN or an infinity, which do not + exist in MPF. If OP is NaN, then ROP is undefined. If OP is +Inf + (resp. −Inf), then ROP is set to the maximum (resp. minimum) value + in the precision of the MPF number; if a future MPF version + supports infinities, this behavior will be considered incorrect and + will change (portable programs should assume that ROP is set either + to this finite number or to an infinite number). Note that since + MPFR currently has the same exponent type as MPF (but not with the + same radix), the range of values is much larger in MPF than in + MPFR, so that an overflow or underflow is not possible. + + -- Function: char * mpfr_get_str (char *STR, mpfr_exp_t *EXPPTR, int B, + size_t N, mpfr_t OP, mpfr_rnd_t RND) + Convert OP to a string of digits in base B, with rounding in the + direction RND, where N is either zero (see below) or the number of + significant digits output in the string; in the latter case, N must + be greater or equal to 2. The base may vary from 2 to 62; + otherwise the function does nothing and immediately returns a null + pointer. If the input number is an ordinary number, the exponent + is written through the pointer EXPPTR (for input 0, the current + minimal exponent is written); the type ‘mpfr_exp_t’ is large enough + to hold the exponent in all cases. + + The generated string is a fraction, with an implicit radix point + immediately to the left of the first digit. For example, the + number −3.1416 would be returned as "−31416" in the string and 1 + written at EXPPTR. If RND is to nearest, and OP is exactly in the + middle of two consecutive possible outputs, the one with an even + significand is chosen, where both significands are considered with + the exponent of OP. Note that for an odd base, this may not + correspond to an even last digit: for example with 2 digits in base + 7, (14) and a half is rounded to (15) which is 12 in decimal, (16) + and a half is rounded to (20) which is 14 in decimal, and (26) and + a half is rounded to (26) which is 20 in decimal. + + If N is zero, the number of digits of the significand is chosen + large enough so that re-reading the printed value with the same + precision, assuming both output and input use rounding to nearest, + will recover the original value of OP. More precisely, in most + cases, the chosen precision of STR is the minimal precision m + depending only on P = PREC(OP) and B that satisfies the above + property, i.e., m = 1 + ceil(P*log(2)/log(B)), with P replaced by + P−1 if B is a power of 2, but in some very rare cases, it might be + m+1 (the smallest case for bases up to 62 is when P equals + 186564318007 for bases 7 and 49). + + If STR is a null pointer, space for the significand is allocated + using the current allocation function and a pointer to the string + is returned (unless the base is invalid). To free the returned + string, you must use ‘mpfr_free_str’. + + If STR is not a null pointer, it should point to a block of storage + large enough for the significand, i.e., at least ‘max(N + 2, 7)’. + The extra two bytes are for a possible minus sign, and for the + terminating null character, and the value 7 accounts for ‘-@Inf@’ + plus the terminating null character. The pointer to the string STR + is returned (unless the base is invalid). + + Note: The NaN and inexact flags are currently not set when need be; + this will be fixed in future versions. Programmers should + currently assume that whether the flags are set by this function is + unspecified. + + -- Function: void mpfr_free_str (char *STR) + Free a string allocated by ‘mpfr_get_str’ using the current + unallocation function. The block is assumed to be ‘strlen(STR)+1’ + bytes. For more information about how it is done: *note + (gmp.info)Custom Allocation::. + + -- Function: int mpfr_fits_ulong_p (mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_fits_slong_p (mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_fits_uint_p (mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_fits_sint_p (mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_fits_ushort_p (mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_fits_sshort_p (mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_fits_uintmax_p (mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_fits_intmax_p (mpfr_t OP, mpfr_rnd_t RND) + Return non-zero if OP would fit in the respective C data type, + respectively ‘unsigned long’, ‘long’, ‘unsigned int’, ‘int’, + ‘unsigned short’, ‘short’, ‘uintmax_t’, ‘intmax_t’, when rounded to + an integer in the direction RND. + + +File: mpfr.info, Node: Basic Arithmetic Functions, Next: Comparison Functions, Prev: Conversion Functions, Up: MPFR Interface + +5.5 Basic Arithmetic Functions +============================== + + -- Function: int mpfr_add (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_add_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int + OP2, mpfr_rnd_t RND) + -- Function: int mpfr_add_si (mpfr_t ROP, mpfr_t OP1, long int OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_add_d (mpfr_t ROP, mpfr_t OP1, double OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_add_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_add_q (mpfr_t ROP, mpfr_t OP1, mpq_t OP2, + mpfr_rnd_t RND) + Set ROP to OP1 + OP2 rounded in the direction RND. For types + having no signed zero, it is considered unsigned (i.e., (+0) + 0 = + (+0) and (−0) + 0 = (−0)). The ‘mpfr_add_d’ function assumes that + the radix of the ‘double’ type is a power of 2, with a precision at + most that declared by the C implementation (macro + ‘IEEE_DBL_MANT_DIG’, and if not defined 53 bits). + + -- Function: int mpfr_sub (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_ui_sub (mpfr_t ROP, unsigned long int OP1, mpfr_t + OP2, mpfr_rnd_t RND) + -- Function: int mpfr_sub_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int + OP2, mpfr_rnd_t RND) + -- Function: int mpfr_si_sub (mpfr_t ROP, long int OP1, mpfr_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_sub_si (mpfr_t ROP, mpfr_t OP1, long int OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_d_sub (mpfr_t ROP, double OP1, mpfr_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_sub_d (mpfr_t ROP, mpfr_t OP1, double OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_z_sub (mpfr_t ROP, mpz_t OP1, mpfr_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_sub_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_sub_q (mpfr_t ROP, mpfr_t OP1, mpq_t OP2, + mpfr_rnd_t RND) + Set ROP to OP1 - OP2 rounded in the direction RND. For types + having no signed zero, it is considered unsigned (i.e., (+0) − 0 = + (+0), (−0) − 0 = (−0), 0 − (+0) = (−0) and 0 − (−0) = (+0)). The + same restrictions than for ‘mpfr_add_d’ apply to ‘mpfr_d_sub’ and + ‘mpfr_sub_d’. + + -- Function: int mpfr_mul (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_mul_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int + OP2, mpfr_rnd_t RND) + -- Function: int mpfr_mul_si (mpfr_t ROP, mpfr_t OP1, long int OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_mul_d (mpfr_t ROP, mpfr_t OP1, double OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_mul_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_mul_q (mpfr_t ROP, mpfr_t OP1, mpq_t OP2, + mpfr_rnd_t RND) + Set ROP to OP1 times OP2 rounded in the direction RND. When a + result is zero, its sign is the product of the signs of the + operands (for types having no signed zero, it is considered + positive). The same restrictions than for ‘mpfr_add_d’ apply to + ‘mpfr_mul_d’. + + -- Function: int mpfr_sqr (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the square of OP rounded in the direction RND. + + -- Function: int mpfr_div (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_ui_div (mpfr_t ROP, unsigned long int OP1, mpfr_t + OP2, mpfr_rnd_t RND) + -- Function: int mpfr_div_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int + OP2, mpfr_rnd_t RND) + -- Function: int mpfr_si_div (mpfr_t ROP, long int OP1, mpfr_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_div_si (mpfr_t ROP, mpfr_t OP1, long int OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_d_div (mpfr_t ROP, double OP1, mpfr_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_div_d (mpfr_t ROP, mpfr_t OP1, double OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_div_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_div_q (mpfr_t ROP, mpfr_t OP1, mpq_t OP2, + mpfr_rnd_t RND) + Set ROP to OP1/OP2 rounded in the direction RND. When a result is + zero, its sign is the product of the signs of the operands (for + types having no signed zero, it is considered positive). The same + restrictions than for ‘mpfr_add_d’ apply to ‘mpfr_d_div’ and + ‘mpfr_div_d’. + + -- Function: int mpfr_sqrt (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_sqrt_ui (mpfr_t ROP, unsigned long int OP, + mpfr_rnd_t RND) + Set ROP to the square root of OP rounded in the direction RND (set + ROP to −0 if OP is −0, to be consistent with the IEEE 754 + standard). Set ROP to NaN if OP is negative. + + -- Function: int mpfr_rec_sqrt (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the reciprocal square root of OP rounded in the + direction RND. Set ROP to +Inf if OP is ±0, +0 if OP is +Inf, and + NaN if OP is negative. + + -- Function: int mpfr_cbrt (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_root (mpfr_t ROP, mpfr_t OP, unsigned long int K, + mpfr_rnd_t RND) + Set ROP to the cubic root (resp. the Kth root) of OP rounded in the + direction RND. For K odd (resp. even) and OP negative (including + −Inf), set ROP to a negative number (resp. NaN). The Kth root of −0 + is defined to be −0, whatever the parity of K. + + -- Function: int mpfr_pow (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_pow_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int + OP2, mpfr_rnd_t RND) + -- Function: int mpfr_pow_si (mpfr_t ROP, mpfr_t OP1, long int OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_pow_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_ui_pow_ui (mpfr_t ROP, unsigned long int OP1, + unsigned long int OP2, mpfr_rnd_t RND) + -- Function: int mpfr_ui_pow (mpfr_t ROP, unsigned long int OP1, mpfr_t + OP2, mpfr_rnd_t RND) + Set ROP to OP1 raised to OP2, rounded in the direction RND. + Special values are handled as described in the ISO C99 and IEEE + 754-2008 standards for the ‘pow’ function: + • ‘pow(±0, Y)’ returns plus or minus infinity for Y a negative + odd integer. + • ‘pow(±0, Y)’ returns plus infinity for Y negative and not an + odd integer. + • ‘pow(±0, Y)’ returns plus or minus zero for Y a positive odd + integer. + • ‘pow(±0, Y)’ returns plus zero for Y positive and not an odd + integer. + • ‘pow(-1, ±Inf)’ returns 1. + • ‘pow(+1, Y)’ returns 1 for any Y, even a NaN. + • ‘pow(X, ±0)’ returns 1 for any X, even a NaN. + • ‘pow(X, Y)’ returns NaN for finite negative X and finite + non-integer Y. + • ‘pow(X, -Inf)’ returns plus infinity for 0 < abs(x) < 1, and + plus zero for abs(x) > 1. + • ‘pow(X, +Inf)’ returns plus zero for 0 < abs(x) < 1, and plus + infinity for abs(x) > 1. + • ‘pow(-Inf, Y)’ returns minus zero for Y a negative odd + integer. + • ‘pow(-Inf, Y)’ returns plus zero for Y negative and not an odd + integer. + • ‘pow(-Inf, Y)’ returns minus infinity for Y a positive odd + integer. + • ‘pow(-Inf, Y)’ returns plus infinity for Y positive and not an + odd integer. + • ‘pow(+Inf, Y)’ returns plus zero for Y negative, and plus + infinity for Y positive. + + -- Function: int mpfr_neg (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_abs (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to -OP and the absolute value of OP respectively, rounded + in the direction RND. Just changes or adjusts the sign if ROP and + OP are the same variable, otherwise a rounding might occur if the + precision of ROP is less than that of OP. + + -- Function: int mpfr_dim (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, + mpfr_rnd_t RND) + Set ROP to the positive difference of OP1 and OP2, i.e., OP1 - OP2 + rounded in the direction RND if OP1 > OP2, +0 if OP1 <= OP2, and + NaN if OP1 or OP2 is NaN. + + -- Function: int mpfr_mul_2ui (mpfr_t ROP, mpfr_t OP1, unsigned long + int OP2, mpfr_rnd_t RND) + -- Function: int mpfr_mul_2si (mpfr_t ROP, mpfr_t OP1, long int OP2, + mpfr_rnd_t RND) + Set ROP to OP1 times 2 raised to OP2 rounded in the direction RND. + Just increases the exponent by OP2 when ROP and OP1 are identical. + + -- Function: int mpfr_div_2ui (mpfr_t ROP, mpfr_t OP1, unsigned long + int OP2, mpfr_rnd_t RND) + -- Function: int mpfr_div_2si (mpfr_t ROP, mpfr_t OP1, long int OP2, + mpfr_rnd_t RND) + Set ROP to OP1 divided by 2 raised to OP2 rounded in the direction + RND. Just decreases the exponent by OP2 when ROP and OP1 are + identical. + + +File: mpfr.info, Node: Comparison Functions, Next: Special Functions, Prev: Basic Arithmetic Functions, Up: MPFR Interface + +5.6 Comparison Functions +======================== + + -- Function: int mpfr_cmp (mpfr_t OP1, mpfr_t OP2) + -- Function: int mpfr_cmp_ui (mpfr_t OP1, unsigned long int OP2) + -- Function: int mpfr_cmp_si (mpfr_t OP1, long int OP2) + -- Function: int mpfr_cmp_d (mpfr_t OP1, double OP2) + -- Function: int mpfr_cmp_ld (mpfr_t OP1, long double OP2) + -- Function: int mpfr_cmp_z (mpfr_t OP1, mpz_t OP2) + -- Function: int mpfr_cmp_q (mpfr_t OP1, mpq_t OP2) + -- Function: int mpfr_cmp_f (mpfr_t OP1, mpf_t OP2) + Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero if + OP1 = OP2, and a negative value if OP1 < OP2. Both OP1 and OP2 are + considered to their full own precision, which may differ. If one + of the operands is NaN, set the _erange_ flag and return zero. + + Note: These functions may be useful to distinguish the three + possible cases. If you need to distinguish two cases only, it is + recommended to use the predicate functions (e.g., ‘mpfr_equal_p’ + for the equality) described below; they behave like the IEEE 754 + comparisons, in particular when one or both arguments are NaN. But + only floating-point numbers can be compared (you may need to do a + conversion first). + + -- Function: int mpfr_cmp_ui_2exp (mpfr_t OP1, unsigned long int OP2, + mpfr_exp_t E) + -- Function: int mpfr_cmp_si_2exp (mpfr_t OP1, long int OP2, mpfr_exp_t + E) + Compare OP1 and OP2 multiplied by two to the power E. Similar as + above. + + -- Function: int mpfr_cmpabs (mpfr_t OP1, mpfr_t OP2) + Compare |OP1| and |OP2|. Return a positive value if |OP1| > |OP2|, + zero if |OP1| = |OP2|, and a negative value if |OP1| < |OP2|. If + one of the operands is NaN, set the _erange_ flag and return zero. + + -- Function: int mpfr_nan_p (mpfr_t OP) + -- Function: int mpfr_inf_p (mpfr_t OP) + -- Function: int mpfr_number_p (mpfr_t OP) + -- Function: int mpfr_zero_p (mpfr_t OP) + -- Function: int mpfr_regular_p (mpfr_t OP) + Return non-zero if OP is respectively NaN, an infinity, an ordinary + number (i.e., neither NaN nor an infinity), zero, or a regular + number (i.e., neither NaN, nor an infinity nor zero). Return zero + otherwise. + + -- Macro: int mpfr_sgn (mpfr_t OP) + Return a positive value if OP > 0, zero if OP = 0, and a negative + value if OP < 0. If the operand is NaN, set the _erange_ flag and + return zero. This is equivalent to ‘mpfr_cmp_ui (op, 0)’, but more + efficient. + + -- Function: int mpfr_greater_p (mpfr_t OP1, mpfr_t OP2) + -- Function: int mpfr_greaterequal_p (mpfr_t OP1, mpfr_t OP2) + -- Function: int mpfr_less_p (mpfr_t OP1, mpfr_t OP2) + -- Function: int mpfr_lessequal_p (mpfr_t OP1, mpfr_t OP2) + -- Function: int mpfr_equal_p (mpfr_t OP1, mpfr_t OP2) + Return non-zero if OP1 > OP2, OP1 >= OP2, OP1 < OP2, OP1 <= OP2, + OP1 = OP2 respectively, and zero otherwise. Those functions return + zero whenever OP1 and/or OP2 is NaN. + + -- Function: int mpfr_lessgreater_p (mpfr_t OP1, mpfr_t OP2) + Return non-zero if OP1 < OP2 or OP1 > OP2 (i.e., neither OP1, nor + OP2 is NaN, and OP1 <> OP2), zero otherwise (i.e., OP1 and/or OP2 + is NaN, or OP1 = OP2). + + -- Function: int mpfr_unordered_p (mpfr_t OP1, mpfr_t OP2) + Return non-zero if OP1 or OP2 is a NaN (i.e., they cannot be + compared), zero otherwise. + + +File: mpfr.info, Node: Special Functions, Next: Input and Output Functions, Prev: Comparison Functions, Up: MPFR Interface + +5.7 Special Functions +===================== + +All those functions, except explicitly stated (for example +‘mpfr_sin_cos’), return a *note ternary value::, i.e., zero for an exact +return value, a positive value for a return value larger than the exact +result, and a negative value otherwise. + + Important note: in some domains, computing special functions (either +with correct or incorrect rounding) is expensive, even for small +precision, for example the trigonometric and Bessel functions for large +argument. + + -- Function: int mpfr_log (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_log2 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_log10 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the natural logarithm of OP, log2(OP) or log10(OP), + respectively, rounded in the direction RND. Set ROP to −Inf if OP + is −0 (i.e., the sign of the zero has no influence on the result). + + -- Function: int mpfr_exp (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_exp2 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_exp10 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the exponential of OP, to 2 power of OP or to 10 power + of OP, respectively, rounded in the direction RND. + + -- Function: int mpfr_cos (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_sin (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_tan (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the cosine of OP, sine of OP, tangent of OP, rounded in + the direction RND. + + -- Function: int mpfr_sin_cos (mpfr_t SOP, mpfr_t COP, mpfr_t OP, + mpfr_rnd_t RND) + Set simultaneously SOP to the sine of OP and COP to the cosine of + OP, rounded in the direction RND with the corresponding precisions + of SOP and COP, which must be different variables. Return 0 iff + both results are exact, more precisely it returns s+4c where s=0 if + SOP is exact, s=1 if SOP is larger than the sine of OP, s=2 if SOP + is smaller than the sine of OP, and similarly for c and the cosine + of OP. + + -- Function: int mpfr_sec (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_csc (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_cot (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the secant of OP, cosecant of OP, cotangent of OP, + rounded in the direction RND. + + -- Function: int mpfr_acos (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_asin (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_atan (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the arc-cosine, arc-sine or arc-tangent of OP, rounded + in the direction RND. Note that since ‘acos(-1)’ returns the + floating-point number closest to Pi according to the given rounding + mode, this number might not be in the output range 0 <= ROP < \pi + of the arc-cosine function; still, the result lies in the image of + the output range by the rounding function. The same holds for + ‘asin(-1)’, ‘asin(1)’, ‘atan(-Inf)’, ‘atan(+Inf)’ or for ‘atan(op)’ + with large OP and small precision of ROP. + + -- Function: int mpfr_atan2 (mpfr_t ROP, mpfr_t Y, mpfr_t X, mpfr_rnd_t + RND) + Set ROP to the arc-tangent2 of Y and X, rounded in the direction + RND: if ‘x > 0’, ‘atan2(y, x) = atan (y/x)’; if ‘x < 0’, ‘atan2(y, + x) = sign(y)*(Pi - atan (abs(y/x)))’, thus a number from -Pi to Pi. + As for ‘atan’, in case the exact mathematical result is +Pi or -Pi, + its rounded result might be outside the function output range. + + ‘atan2(y, 0)’ does not raise any floating-point exception. Special + values are handled as described in the ISO C99 and IEEE 754-2008 + standards for the ‘atan2’ function: + • ‘atan2(+0, -0)’ returns +Pi. + • ‘atan2(-0, -0)’ returns -Pi. + • ‘atan2(+0, +0)’ returns +0. + • ‘atan2(-0, +0)’ returns −0. + • ‘atan2(+0, x)’ returns +Pi for x < 0. + • ‘atan2(-0, x)’ returns -Pi for x < 0. + • ‘atan2(+0, x)’ returns +0 for x > 0. + • ‘atan2(-0, x)’ returns −0 for x > 0. + • ‘atan2(y, 0)’ returns -Pi/2 for y < 0. + • ‘atan2(y, 0)’ returns +Pi/2 for y > 0. + • ‘atan2(+Inf, -Inf)’ returns +3*Pi/4. + • ‘atan2(-Inf, -Inf)’ returns -3*Pi/4. + • ‘atan2(+Inf, +Inf)’ returns +Pi/4. + • ‘atan2(-Inf, +Inf)’ returns -Pi/4. + • ‘atan2(+Inf, x)’ returns +Pi/2 for finite x. + • ‘atan2(-Inf, x)’ returns -Pi/2 for finite x. + • ‘atan2(y, -Inf)’ returns +Pi for finite y > 0. + • ‘atan2(y, -Inf)’ returns -Pi for finite y < 0. + • ‘atan2(y, +Inf)’ returns +0 for finite y > 0. + • ‘atan2(y, +Inf)’ returns −0 for finite y < 0. + + -- Function: int mpfr_cosh (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_sinh (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_tanh (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the hyperbolic cosine, sine or tangent of OP, rounded in + the direction RND. + + -- Function: int mpfr_sinh_cosh (mpfr_t SOP, mpfr_t COP, mpfr_t OP, + mpfr_rnd_t RND) + Set simultaneously SOP to the hyperbolic sine of OP and COP to the + hyperbolic cosine of OP, rounded in the direction RND with the + corresponding precision of SOP and COP, which must be different + variables. Return 0 iff both results are exact (see ‘mpfr_sin_cos’ + for a more detailed description of the return value). + + -- Function: int mpfr_sech (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_csch (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_coth (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the hyperbolic secant of OP, cosecant of OP, cotangent + of OP, rounded in the direction RND. + + -- Function: int mpfr_acosh (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_asinh (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_atanh (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the inverse hyperbolic cosine, sine or tangent of OP, + rounded in the direction RND. + + -- Function: int mpfr_fac_ui (mpfr_t ROP, unsigned long int OP, + mpfr_rnd_t RND) + Set ROP to the factorial of OP, rounded in the direction RND. + + -- Function: int mpfr_log1p (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the logarithm of one plus OP, rounded in the direction + RND. + + -- Function: int mpfr_expm1 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the exponential of OP followed by a subtraction by one, + rounded in the direction RND. + + -- Function: int mpfr_eint (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the exponential integral of OP, rounded in the direction + RND. For positive OP, the exponential integral is the sum of + Euler’s constant, of the logarithm of OP, and of the sum for k from + 1 to infinity of OP to the power k, divided by k and factorial(k). + For negative OP, ROP is set to NaN (this definition for negative + argument follows formula 5.1.2 from the Handbook of Mathematical + Functions from Abramowitz and Stegun, a future version might use + another definition). + + -- Function: int mpfr_li2 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to real part of the dilogarithm of OP, rounded in the + direction RND. MPFR defines the dilogarithm function as the + integral of -log(1-t)/t from 0 to OP. + + -- Function: int mpfr_gamma (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the value of the Gamma function on OP, rounded in the + direction RND. When OP is a negative integer, ROP is set to NaN. + + -- Function: int mpfr_lngamma (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the value of the logarithm of the Gamma function on OP, + rounded in the direction RND. When −2K−1 <= OP <= −2K, K being a + non-negative integer, ROP is set to NaN. See also ‘mpfr_lgamma’. + + -- Function: int mpfr_lgamma (mpfr_t ROP, int *SIGNP, mpfr_t OP, + mpfr_rnd_t RND) + Set ROP to the value of the logarithm of the absolute value of the + Gamma function on OP, rounded in the direction RND. The sign (1 or + −1) of Gamma(OP) is returned in the object pointed to by SIGNP. + When OP is an infinity or a non-positive integer, set ROP to +Inf. + When OP is NaN, −Inf or a negative integer, *SIGNP is undefined, + and when OP is ±0, *SIGNP is the sign of the zero. + + -- Function: int mpfr_digamma (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the value of the Digamma (sometimes also called Psi) + function on OP, rounded in the direction RND. When OP is a + negative integer, set ROP to NaN. + + -- Function: int mpfr_zeta (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_zeta_ui (mpfr_t ROP, unsigned long OP, mpfr_rnd_t + RND) + Set ROP to the value of the Riemann Zeta function on OP, rounded in + the direction RND. + + -- Function: int mpfr_erf (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_erfc (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the value of the error function on OP (resp. the + complementary error function on OP) rounded in the direction RND. + + -- Function: int mpfr_j0 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_j1 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_jn (mpfr_t ROP, long N, mpfr_t OP, mpfr_rnd_t + RND) + Set ROP to the value of the first kind Bessel function of order 0, + (resp. 1 and N) on OP, rounded in the direction RND. When OP is + NaN, ROP is always set to NaN. When OP is plus or minus Infinity, + ROP is set to +0. When OP is zero, and N is not zero, ROP is set + to +0 or −0 depending on the parity and sign of N, and the sign of + OP. + + -- Function: int mpfr_y0 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_y1 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_yn (mpfr_t ROP, long N, mpfr_t OP, mpfr_rnd_t + RND) + Set ROP to the value of the second kind Bessel function of order 0 + (resp. 1 and N) on OP, rounded in the direction RND. When OP is + NaN or negative, ROP is always set to NaN. When OP is +Inf, ROP is + set to +0. When OP is zero, ROP is set to +Inf or −Inf depending + on the parity and sign of N. + + -- Function: int mpfr_fma (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, mpfr_t + OP3, mpfr_rnd_t RND) + -- Function: int mpfr_fms (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, mpfr_t + OP3, mpfr_rnd_t RND) + Set ROP to (OP1 times OP2) + OP3 (resp. (OP1 times OP2) - OP3) + rounded in the direction RND. + + -- Function: int mpfr_agm (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, + mpfr_rnd_t RND) + Set ROP to the arithmetic-geometric mean of OP1 and OP2, rounded in + the direction RND. The arithmetic-geometric mean is the common + limit of the sequences U_N and V_N, where U_0=OP1, V_0=OP2, U_(N+1) + is the arithmetic mean of U_N and V_N, and V_(N+1) is the geometric + mean of U_N and V_N. If any operand is negative, set ROP to NaN. + + -- Function: int mpfr_hypot (mpfr_t ROP, mpfr_t X, mpfr_t Y, mpfr_rnd_t + RND) + Set ROP to the Euclidean norm of X and Y, i.e., the square root of + the sum of the squares of X and Y, rounded in the direction RND. + Special values are handled as described in Section F.9.4.3 of the + ISO C99 and IEEE 754-2008 standards: If X or Y is an infinity, then + +Inf is returned in ROP, even if the other number is NaN. + + -- Function: int mpfr_ai (mpfr_t ROP, mpfr_t X, mpfr_rnd_t RND) + Set ROP to the value of the Airy function Ai on X, rounded in the + direction RND. When X is NaN, ROP is always set to NaN. When X is + +Inf or −Inf, ROP is +0. The current implementation is not + intended to be used with large arguments. It works with abs(X) + typically smaller than 500. For larger arguments, other methods + should be used and will be implemented in a future version. + + -- Function: int mpfr_const_log2 (mpfr_t ROP, mpfr_rnd_t RND) + -- Function: int mpfr_const_pi (mpfr_t ROP, mpfr_rnd_t RND) + -- Function: int mpfr_const_euler (mpfr_t ROP, mpfr_rnd_t RND) + -- Function: int mpfr_const_catalan (mpfr_t ROP, mpfr_rnd_t RND) + Set ROP to the logarithm of 2, the value of Pi, of Euler’s constant + 0.577…, of Catalan’s constant 0.915…, respectively, rounded in the + direction RND. These functions cache the computed values to avoid + other calculations if a lower or equal precision is requested. To + free these caches, use ‘mpfr_free_cache’. + + -- Function: void mpfr_free_cache (void) + Free various caches used by MPFR internally, in particular the + caches used by the functions computing constants + (‘mpfr_const_log2’, ‘mpfr_const_pi’, ‘mpfr_const_euler’ and + ‘mpfr_const_catalan’). You should call this function before + terminating a thread, even if you did not call these functions + directly (they could have been called internally). + + -- Function: int mpfr_sum (mpfr_t ROP, mpfr_ptr const TAB[], unsigned + long int N, mpfr_rnd_t RND) + Set ROP to the sum of all elements of TAB, whose size is N, rounded + in the direction RND. Warning: for efficiency reasons, TAB is an + array of pointers to ‘mpfr_t’, not an array of ‘mpfr_t’. If the + returned ‘int’ value is zero, ROP is guaranteed to be the exact + sum; otherwise ROP might be smaller than, equal to, or larger than + the exact sum (in accordance to the rounding mode). However, + ‘mpfr_sum’ does guarantee the result is correctly rounded. + + +File: mpfr.info, Node: Input and Output Functions, Next: Formatted Output Functions, Prev: Special Functions, Up: MPFR Interface + +5.8 Input and Output Functions +============================== + +This section describes functions that perform input from an input/output +stream, and functions that output to an input/output stream. Passing a +null pointer for a ‘stream’ to any of these functions will make them +read from ‘stdin’ and write to ‘stdout’, respectively. + + When using any of these functions, you must include the ‘<stdio.h>’ +standard header before ‘mpfr.h’, to allow ‘mpfr.h’ to define prototypes +for these functions. + + -- Function: size_t mpfr_out_str (FILE *STREAM, int BASE, size_t N, + mpfr_t OP, mpfr_rnd_t RND) + Output OP on stream STREAM, as a string of digits in base BASE, + rounded in the direction RND. The base may vary from 2 to 62. + Print N significant digits exactly, or if N is 0, enough digits so + that OP can be read back exactly (see ‘mpfr_get_str’). + + In addition to the significant digits, a decimal point (defined by + the current locale) at the right of the first digit and a trailing + exponent in base 10, in the form ‘eNNN’, are printed. If BASE is + greater than 10, ‘@’ will be used instead of ‘e’ as exponent + delimiter. + + Return the number of characters written, or if an error occurred, + return 0. + + -- Function: size_t mpfr_inp_str (mpfr_t ROP, FILE *STREAM, int BASE, + mpfr_rnd_t RND) + Input a string in base BASE from stream STREAM, rounded in the + direction RND, and put the read float in ROP. + + This function reads a word (defined as a sequence of characters + between whitespace) and parses it using ‘mpfr_set_str’. See the + documentation of ‘mpfr_strtofr’ for a detailed description of the + valid string formats. + + Return the number of bytes read, or if an error occurred, return 0. + + +File: mpfr.info, Node: Formatted Output Functions, Next: Integer Related Functions, Prev: Input and Output Functions, Up: MPFR Interface + +5.9 Formatted Output Functions +============================== + +5.9.1 Requirements +------------------ + +The class of ‘mpfr_printf’ functions provides formatted output in a +similar manner as the standard C ‘printf’. These functions are defined +only if your system supports ISO C variadic functions and the +corresponding argument access macros. + + When using any of these functions, you must include the ‘<stdio.h>’ +standard header before ‘mpfr.h’, to allow ‘mpfr.h’ to define prototypes +for these functions. + +5.9.2 Format String +------------------- + +The format specification accepted by ‘mpfr_printf’ is an extension of +the ‘printf’ one. The conversion specification is of the form: + % [flags] [width] [.[precision]] [type] [rounding] conv + ‘flags’, ‘width’, and ‘precision’ have the same meaning as for the +standard ‘printf’ (in particular, notice that the ‘precision’ is related +to the number of digits displayed in the base chosen by ‘conv’ and not +related to the internal precision of the ‘mpfr_t’ variable). +‘mpfr_printf’ accepts the same ‘type’ specifiers as GMP (except the +non-standard and deprecated ‘q’, use ‘ll’ instead), namely the length +modifiers defined in the C standard: + + ‘h’ ‘short’ + ‘hh’ ‘char’ + ‘j’ ‘intmax_t’ or ‘uintmax_t’ + ‘l’ ‘long’ or ‘wchar_t’ + ‘ll’ ‘long long’ + ‘L’ ‘long double’ + ‘t’ ‘ptrdiff_t’ + ‘z’ ‘size_t’ + + and the ‘type’ specifiers defined in GMP plus ‘R’ and ‘P’ specific to +MPFR (the second column in the table below shows the type of the +argument read in the argument list and the kind of ‘conv’ specifier to +use after the ‘type’ specifier): + + ‘F’ ‘mpf_t’, float conversions + ‘Q’ ‘mpq_t’, integer conversions + ‘M’ ‘mp_limb_t’, integer conversions + ‘N’ ‘mp_limb_t’ array, integer conversions + ‘Z’ ‘mpz_t’, integer conversions + + ‘P’ ‘mpfr_prec_t’, integer conversions + ‘R’ ‘mpfr_t’, float conversions + + The ‘type’ specifiers have the same restrictions as those mentioned +in the GMP documentation: *note (gmp.info)Formatted Output Strings::. +In particular, the ‘type’ specifiers (except ‘R’ and ‘P’) are supported +only if they are supported by ‘gmp_printf’ in your GMP build; this +implies that the standard specifiers, such as ‘t’, must _also_ be +supported by your C library if you want to use them. + + The ‘rounding’ field is specific to ‘mpfr_t’ arguments and should not +be used with other types. + + With conversion specification not involving ‘P’ and ‘R’ types, +‘mpfr_printf’ behaves exactly as ‘gmp_printf’. + + The ‘P’ type specifies that a following ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, or +‘X’ conversion specifier applies to a ‘mpfr_prec_t’ argument. It is +needed because the ‘mpfr_prec_t’ type does not necessarily correspond to +an ‘int’ or any fixed standard type. The ‘precision’ field specifies +the minimum number of digits to appear. The default ‘precision’ is 1. +For example: + mpfr_t x; + mpfr_prec_t p; + mpfr_init (x); + … + p = mpfr_get_prec (x); + mpfr_printf ("variable x with %Pu bits", p); + + The ‘R’ type specifies that a following ‘a’, ‘A’, ‘b’, ‘e’, ‘E’, ‘f’, +‘F’, ‘g’, ‘G’, or ‘n’ conversion specifier applies to a ‘mpfr_t’ +argument. The ‘R’ type can be followed by a ‘rounding’ specifier +denoted by one of the following characters: + + ‘U’ round toward plus infinity + ‘D’ round toward minus infinity + ‘Y’ round away from zero + ‘Z’ round toward zero + ‘N’ round to nearest (with ties to even) + ‘*’ rounding mode indicated by the + ‘mpfr_rnd_t’ argument just before the + corresponding ‘mpfr_t’ variable. + + The default rounding mode is rounding to nearest. The following +three examples are equivalent: + mpfr_t x; + mpfr_init (x); + … + mpfr_printf ("%.128Rf", x); + mpfr_printf ("%.128RNf", x); + mpfr_printf ("%.128R*f", MPFR_RNDN, x); + + Note that the rounding away from zero mode is specified with ‘Y’ +because ISO C reserves the ‘A’ specifier for hexadecimal output (see +below). + + The output ‘conv’ specifiers allowed with ‘mpfr_t’ parameter are: + + ‘a’ ‘A’ hex float, C99 style + ‘b’ binary output + ‘e’ ‘E’ scientific format float + ‘f’ ‘F’ fixed point float + ‘g’ ‘G’ fixed or scientific float + + The conversion specifier ‘b’ which displays the argument in binary is +specific to ‘mpfr_t’ arguments and should not be used with other types. +Other conversion specifiers have the same meaning as for a ‘double’ +argument. + + In case of non-decimal output, only the significand is written in the +specified base, the exponent is always displayed in decimal. Special +values are always displayed as ‘nan’, ‘-inf’, and ‘inf’ for ‘a’, ‘b’, +‘e’, ‘f’, and ‘g’ specifiers and ‘NAN’, ‘-INF’, and ‘INF’ for ‘A’, ‘E’, +‘F’, and ‘G’ specifiers. + + If the ‘precision’ field is not empty, the ‘mpfr_t’ number is rounded +to the given precision in the direction specified by the rounding mode. +If the precision is zero with rounding to nearest mode and one of the +following ‘conv’ specifiers: ‘a’, ‘A’, ‘b’, ‘e’, ‘E’, tie case is +rounded to even when it lies between two consecutive values at the +wanted precision which have the same exponent, otherwise, it is rounded +away from zero. For instance, 85 is displayed as "8e+1" and 95 is +displayed as "1e+2" with the format specification ‘"%.0RNe"’. This also +applies when the ‘g’ (resp. ‘G’) conversion specifier uses the ‘e’ +(resp. ‘E’) style. If the precision is set to a value greater than the +maximum value for an ‘int’, it will be silently reduced down to +‘INT_MAX’. + + If the ‘precision’ field is empty (as in ‘%Re’ or ‘%.RE’) with ‘conv’ +specifier ‘e’ and ‘E’, the number is displayed with enough digits so +that it can be read back exactly, assuming that the input and output +variables have the same precision and that the input and output rounding +modes are both rounding to nearest (as for ‘mpfr_get_str’). The default +precision for an empty ‘precision’ field with ‘conv’ specifiers ‘f’, +‘F’, ‘g’, and ‘G’ is 6. + +5.9.3 Functions +--------------- + +For all the following functions, if the number of characters which ought +to be written appears to exceed the maximum limit for an ‘int’, nothing +is written in the stream (resp. to ‘stdout’, to BUF, to STR), the +function returns −1, sets the _erange_ flag, and (in POSIX system only) +‘errno’ is set to ‘EOVERFLOW’. + + -- Function: int mpfr_fprintf (FILE *STREAM, const char *TEMPLATE, …) + -- Function: int mpfr_vfprintf (FILE *STREAM, const char *TEMPLATE, + va_list AP) + Print to the stream STREAM the optional arguments under the control + of the template string TEMPLATE. Return the number of characters + written or a negative value if an error occurred. + + -- Function: int mpfr_printf (const char *TEMPLATE, …) + -- Function: int mpfr_vprintf (const char *TEMPLATE, va_list AP) + Print to ‘stdout’ the optional arguments under the control of the + template string TEMPLATE. Return the number of characters written + or a negative value if an error occurred. + + -- Function: int mpfr_sprintf (char *BUF, const char *TEMPLATE, …) + -- Function: int mpfr_vsprintf (char *BUF, const char *TEMPLATE, + va_list AP) + Form a null-terminated string corresponding to the optional + arguments under the control of the template string TEMPLATE, and + print it in BUF. No overlap is permitted between BUF and the other + arguments. Return the number of characters written in the array + BUF _not counting_ the terminating null character or a negative + value if an error occurred. + + -- Function: int mpfr_snprintf (char *BUF, size_t N, const char + *TEMPLATE, …) + -- Function: int mpfr_vsnprintf (char *BUF, size_t N, const char + *TEMPLATE, va_list AP) + Form a null-terminated string corresponding to the optional + arguments under the control of the template string TEMPLATE, and + print it in BUF. If N is zero, nothing is written and BUF may be a + null pointer, otherwise, the N−1 first characters are written in + BUF and the N-th is a null character. Return the number of + characters that would have been written had N be sufficiently + large, _not counting_ the terminating null character, or a negative + value if an error occurred. + + -- Function: int mpfr_asprintf (char **STR, const char *TEMPLATE, …) + -- Function: int mpfr_vasprintf (char **STR, const char *TEMPLATE, + va_list AP) + Write their output as a null terminated string in a block of memory + allocated using the current allocation function. A pointer to the + block is stored in STR. The block of memory must be freed using + ‘mpfr_free_str’. The return value is the number of characters + written in the string, excluding the null-terminator, or a negative + value if an error occurred. + + +File: mpfr.info, Node: Integer Related Functions, Next: Rounding Related Functions, Prev: Formatted Output Functions, Up: MPFR Interface + +5.10 Integer and Remainder Related Functions +============================================ + + -- Function: int mpfr_rint (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_ceil (mpfr_t ROP, mpfr_t OP) + -- Function: int mpfr_floor (mpfr_t ROP, mpfr_t OP) + -- Function: int mpfr_round (mpfr_t ROP, mpfr_t OP) + -- Function: int mpfr_trunc (mpfr_t ROP, mpfr_t OP) + Set ROP to OP rounded to an integer. ‘mpfr_rint’ rounds to the + nearest representable integer in the given direction RND, + ‘mpfr_ceil’ rounds to the next higher or equal representable + integer, ‘mpfr_floor’ to the next lower or equal representable + integer, ‘mpfr_round’ to the nearest representable integer, + rounding halfway cases away from zero (as in the roundTiesToAway + mode of IEEE 754-2008), and ‘mpfr_trunc’ to the next representable + integer toward zero. + + The returned value is zero when the result is exact, positive when + it is greater than the original value of OP, and negative when it + is smaller. More precisely, the returned value is 0 when OP is an + integer representable in ROP, 1 or −1 when OP is an integer that is + not representable in ROP, 2 or −2 when OP is not an integer. + + When OP is NaN, the NaN flag is set as usual. In the other cases, + the inexact flag is set when ROP differs from OP, following the ISO + C99 rule for the ‘rint’ function. If you want the behavior to be + more like IEEE 754 / ISO TS 18661-1, i.e., the usual behavior where + the round-to-integer function is regarded as any other mathematical + function, you should use one the ‘mpfr_rint_*’ functions instead + (however it is not possible to round to nearest with the even + rounding rule yet). + + Note that ‘mpfr_round’ is different from ‘mpfr_rint’ called with + the rounding to nearest mode (where halfway cases are rounded to an + even integer or significand). Note also that no double rounding is + performed; for instance, 10.5 (1010.1 in binary) is rounded by + ‘mpfr_rint’ with rounding to nearest to 12 (1100 in binary) in + 2-bit precision, because the two enclosing numbers representable on + two bits are 8 and 12, and the closest is 12. (If one first + rounded to an integer, one would round 10.5 to 10 with even + rounding, and then 10 would be rounded to 8 again with even + rounding.) + + -- Function: int mpfr_rint_ceil (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + -- Function: int mpfr_rint_floor (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t + RND) + -- Function: int mpfr_rint_round (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t + RND) + -- Function: int mpfr_rint_trunc (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t + RND) + Set ROP to OP rounded to an integer. ‘mpfr_rint_ceil’ rounds to + the next higher or equal integer, ‘mpfr_rint_floor’ to the next + lower or equal integer, ‘mpfr_rint_round’ to the nearest integer, + rounding halfway cases away from zero, and ‘mpfr_rint_trunc’ to the + next integer toward zero. If the result is not representable, it + is rounded in the direction RND. The returned value is the ternary + value associated with the considered round-to-integer function + (regarded in the same way as any other mathematical function). + + Contrary to ‘mpfr_rint’, those functions do perform a double + rounding: first OP is rounded to the nearest integer in the + direction given by the function name, then this nearest integer (if + not representable) is rounded in the given direction RND. Thus + these round-to-integer functions behave more like the other + mathematical functions, i.e., the returned result is the correct + rounding of the exact result of the function in the real numbers. + + For example, ‘mpfr_rint_round’ with rounding to nearest and a + precision of two bits rounds 6.5 to 7 (halfway cases away from + zero), then 7 is rounded to 8 by the round-even rule, despite the + fact that 6 is also representable on two bits, and is closer to 6.5 + than 8. + + -- Function: int mpfr_frac (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) + Set ROP to the fractional part of OP, having the same sign as OP, + rounded in the direction RND (unlike in ‘mpfr_rint’, RND affects + only how the exact fractional part is rounded, not how the + fractional part is generated). + + -- Function: int mpfr_modf (mpfr_t IOP, mpfr_t FOP, mpfr_t OP, + mpfr_rnd_t RND) + Set simultaneously IOP to the integral part of OP and FOP to the + fractional part of OP, rounded in the direction RND with the + corresponding precision of IOP and FOP (equivalent to + ‘mpfr_trunc(IOP, OP, RND)’ and ‘mpfr_frac(FOP, OP, RND)’). The + variables IOP and FOP must be different. Return 0 iff both results + are exact (see ‘mpfr_sin_cos’ for a more detailed description of + the return value). + + -- Function: int mpfr_fmod (mpfr_t R, mpfr_t X, mpfr_t Y, mpfr_rnd_t + RND) + -- Function: int mpfr_remainder (mpfr_t R, mpfr_t X, mpfr_t Y, + mpfr_rnd_t RND) + -- Function: int mpfr_remquo (mpfr_t R, long* Q, mpfr_t X, mpfr_t Y, + mpfr_rnd_t RND) + Set R to the value of X - NY, rounded according to the direction + RND, where N is the integer quotient of X divided by Y, defined as + follows: N is rounded toward zero for ‘mpfr_fmod’, and to the + nearest integer (ties rounded to even) for ‘mpfr_remainder’ and + ‘mpfr_remquo’. + + Special values are handled as described in Section F.9.7.1 of the + ISO C99 standard: If X is infinite or Y is zero, R is NaN. If Y is + infinite and X is finite, R is X rounded to the precision of R. If + R is zero, it has the sign of X. The return value is the ternary + value corresponding to R. + + Additionally, ‘mpfr_remquo’ stores the low significant bits from + the quotient N in *Q (more precisely the number of bits in a ‘long’ + minus one), with the sign of X divided by Y (except if those low + bits are all zero, in which case zero is returned). Note that X + may be so large in magnitude relative to Y that an exact + representation of the quotient is not practical. The + ‘mpfr_remainder’ and ‘mpfr_remquo’ functions are useful for + additive argument reduction. + + -- Function: int mpfr_integer_p (mpfr_t OP) + Return non-zero iff OP is an integer. + + +File: mpfr.info, Node: Rounding Related Functions, Next: Miscellaneous Functions, Prev: Integer Related Functions, Up: MPFR Interface + +5.11 Rounding Related Functions +=============================== + + -- Function: void mpfr_set_default_rounding_mode (mpfr_rnd_t RND) + Set the default rounding mode to RND. The default rounding mode is + to nearest initially. + + -- Function: mpfr_rnd_t mpfr_get_default_rounding_mode (void) + Get the default rounding mode. + + -- Function: int mpfr_prec_round (mpfr_t X, mpfr_prec_t PREC, + mpfr_rnd_t RND) + Round X according to RND with precision PREC, which must be an + integer between ‘MPFR_PREC_MIN’ and ‘MPFR_PREC_MAX’ (otherwise the + behavior is undefined). If PREC is greater or equal to the + precision of X, then new space is allocated for the significand, + and it is filled with zeros. Otherwise, the significand is rounded + to precision PREC with the given direction. In both cases, the + precision of X is changed to PREC. + + Here is an example of how to use ‘mpfr_prec_round’ to implement + Newton’s algorithm to compute the inverse of A, assuming X is + already an approximation to N bits: + mpfr_set_prec (t, 2 * n); + mpfr_set (t, a, MPFR_RNDN); /* round a to 2n bits */ + mpfr_mul (t, t, x, MPFR_RNDN); /* t is correct to 2n bits */ + mpfr_ui_sub (t, 1, t, MPFR_RNDN); /* high n bits cancel with 1 */ + mpfr_prec_round (t, n, MPFR_RNDN); /* t is correct to n bits */ + mpfr_mul (t, t, x, MPFR_RNDN); /* t is correct to n bits */ + mpfr_prec_round (x, 2 * n, MPFR_RNDN); /* exact */ + mpfr_add (x, x, t, MPFR_RNDN); /* x is correct to 2n bits */ + + Warning! You must not use this function if X was initialized with + ‘MPFR_DECL_INIT’ or with ‘mpfr_custom_init_set’ (*note Custom + Interface::). + + -- Function: int mpfr_can_round (mpfr_t B, mpfr_exp_t ERR, mpfr_rnd_t + RND1, mpfr_rnd_t RND2, mpfr_prec_t PREC) + Assuming B is an approximation of an unknown number X in the + direction RND1 with error at most two to the power E(b)-ERR where + E(b) is the exponent of B, return a non-zero value if one is able + to round correctly X to precision PREC with the direction RND2, and + 0 otherwise (including for NaN and Inf). This function *does not + modify* its arguments. + + If RND1 is ‘MPFR_RNDN’, then the sign of the error is unknown, but + its absolute value is the same, so that the possible range is twice + as large as with a directed rounding for RND1. + + Note: if one wants to also determine the correct *note ternary + value:: when rounding B to precision PREC with rounding mode RND, a + useful trick is the following: + if (mpfr_can_round (b, err, MPFR_RNDN, MPFR_RNDZ, + prec + (rnd == MPFR_RNDN))) + ... + Indeed, if RND is ‘MPFR_RNDN’, this will check if one can round to + PREC+1 bits with a directed rounding: if so, one can surely round + to nearest to PREC bits, and in addition one can determine the + correct ternary value, which would not be the case when B is near + from a value exactly representable on PREC bits. + + -- Function: mpfr_prec_t mpfr_min_prec (mpfr_t X) + Return the minimal number of bits required to store the significand + of X, and 0 for special values, including 0. (Warning: the + returned value can be less than ‘MPFR_PREC_MIN’.) + + The function name is subject to change. + + -- Function: const char * mpfr_print_rnd_mode (mpfr_rnd_t RND) + Return a string ("MPFR_RNDD", "MPFR_RNDU", "MPFR_RNDN", + "MPFR_RNDZ", "MPFR_RNDA") corresponding to the rounding mode RND, + or a null pointer if RND is an invalid rounding mode. + + +File: mpfr.info, Node: Miscellaneous Functions, Next: Exception Related Functions, Prev: Rounding Related Functions, Up: MPFR Interface + +5.12 Miscellaneous Functions +============================ + + -- Function: void mpfr_nexttoward (mpfr_t X, mpfr_t Y) + If X or Y is NaN, set X to NaN. If X and Y are equal, X is + unchanged. Otherwise, if X is different from Y, replace X by the + next floating-point number (with the precision of X and the current + exponent range) in the direction of Y (the infinite values are seen + as the smallest and largest floating-point numbers). If the result + is zero, it keeps the same sign. No underflow or overflow is + generated. + + -- Function: void mpfr_nextabove (mpfr_t X) + -- Function: void mpfr_nextbelow (mpfr_t X) + Equivalent to ‘mpfr_nexttoward’ where Y is plus infinity (resp. + minus infinity). + + -- Function: int mpfr_min (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, + mpfr_rnd_t RND) + -- Function: int mpfr_max (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, + mpfr_rnd_t RND) + Set ROP to the minimum (resp. maximum) of OP1 and OP2. If OP1 and + OP2 are both NaN, then ROP is set to NaN. If OP1 or OP2 is NaN, + then ROP is set to the numeric value. If OP1 and OP2 are zeros of + different signs, then ROP is set to −0 (resp. +0). + + -- Function: int mpfr_urandomb (mpfr_t ROP, gmp_randstate_t STATE) + Generate a uniformly distributed random float in the interval 0 <= + ROP < 1. More precisely, the number can be seen as a float with a + random non-normalized significand and exponent 0, which is then + normalized (thus if E denotes the exponent after normalization, + then the least -E significant bits of the significand are always + 0). + + Return 0, unless the exponent is not in the current exponent range, + in which case ROP is set to NaN and a non-zero value is returned + (this should never happen in practice, except in very specific + cases). The second argument is a ‘gmp_randstate_t’ structure which + should be created using the GMP ‘gmp_randinit’ function (see the + GMP manual). + + Note: for a given version of MPFR, the returned value of ROP and + the new value of STATE (which controls further random values) do + not depend on the machine word size. + + -- Function: int mpfr_urandom (mpfr_t ROP, gmp_randstate_t STATE, + mpfr_rnd_t RND) + Generate a uniformly distributed random float. The floating-point + number ROP can be seen as if a random real number is generated + according to the continuous uniform distribution on the interval + [0, 1] and then rounded in the direction RND. + + The second argument is a ‘gmp_randstate_t’ structure which should + be created using the GMP ‘gmp_randinit’ function (see the GMP + manual). + + Note: the note for ‘mpfr_urandomb’ holds too. In addition, the + exponent range and the rounding mode might have a side effect on + the next random state. + + -- Function: int mpfr_grandom (mpfr_t ROP1, mpfr_t ROP2, + gmp_randstate_t STATE, mpfr_rnd_t RND) + Generate two random floats according to a standard normal gaussian + distribution. If ROP2 is a null pointer, then only one value is + generated and stored in ROP1. + + The floating-point number ROP1 (and ROP2) can be seen as if a + random real number were generated according to the standard normal + gaussian distribution and then rounded in the direction RND. + + The third argument is a ‘gmp_randstate_t’ structure, which should + be created using the GMP ‘gmp_randinit’ function (see the GMP + manual). + + The combination of the ternary values is returned like with + ‘mpfr_sin_cos’. If ROP2 is a null pointer, the second ternary + value is assumed to be 0 (note that the encoding of the only + ternary value is not the same as the usual encoding for functions + that return only one result). Otherwise the ternary value of a + random number is always non-zero. + + Note: the note for ‘mpfr_urandomb’ holds too. In addition, the + exponent range and the rounding mode might have a side effect on + the next random state. + + -- Function: mpfr_exp_t mpfr_get_exp (mpfr_t X) + Return the exponent of X, assuming that X is a non-zero ordinary + number and the significand is considered in [1/2,1). The behavior + for NaN, infinity or zero is undefined. + + -- Function: int mpfr_set_exp (mpfr_t X, mpfr_exp_t E) + Set the exponent of X if E is in the current exponent range, and + return 0 (even if X is not a non-zero ordinary number); otherwise, + return a non-zero value. The significand is assumed to be in + [1/2,1). + + -- Function: int mpfr_signbit (mpfr_t OP) + Return a non-zero value iff OP has its sign bit set (i.e., if it is + negative, −0, or a NaN whose representation has its sign bit set). + + -- Function: int mpfr_setsign (mpfr_t ROP, mpfr_t OP, int S, mpfr_rnd_t + RND) + Set the value of ROP from OP, rounded toward the given direction + RND, then set (resp. clear) its sign bit if S is non-zero (resp. + zero), even when OP is a NaN. + + -- Function: int mpfr_copysign (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, + mpfr_rnd_t RND) + Set the value of ROP from OP1, rounded toward the given direction + RND, then set its sign bit to that of OP2 (even when OP1 or OP2 is + a NaN). This function is equivalent to ‘mpfr_setsign (ROP, OP1, + mpfr_signbit (OP2), RND)’. + + -- Function: const char * mpfr_get_version (void) + Return the MPFR version, as a null-terminated string. + + -- Macro: MPFR_VERSION + -- Macro: MPFR_VERSION_MAJOR + -- Macro: MPFR_VERSION_MINOR + -- Macro: MPFR_VERSION_PATCHLEVEL + -- Macro: MPFR_VERSION_STRING + ‘MPFR_VERSION’ is the version of MPFR as a preprocessing constant. + ‘MPFR_VERSION_MAJOR’, ‘MPFR_VERSION_MINOR’ and + ‘MPFR_VERSION_PATCHLEVEL’ are respectively the major, minor and + patch level of MPFR version, as preprocessing constants. + ‘MPFR_VERSION_STRING’ is the version (with an optional suffix, used + in development and pre-release versions) as a string constant, + which can be compared to the result of ‘mpfr_get_version’ to check + at run time the header file and library used match: + if (strcmp (mpfr_get_version (), MPFR_VERSION_STRING)) + fprintf (stderr, "Warning: header and library do not match\n"); + Note: Obtaining different strings is not necessarily an error, as + in general, a program compiled with some old MPFR version can be + dynamically linked with a newer MPFR library version (if allowed by + the library versioning system). + + -- Macro: long MPFR_VERSION_NUM (MAJOR, MINOR, PATCHLEVEL) + Create an integer in the same format as used by ‘MPFR_VERSION’ from + the given MAJOR, MINOR and PATCHLEVEL. Here is an example of how + to check the MPFR version at compile time: + #if (!defined(MPFR_VERSION) || (MPFR_VERSION<MPFR_VERSION_NUM(3,0,0))) + # error "Wrong MPFR version." + #endif + + -- Function: const char * mpfr_get_patches (void) + Return a null-terminated string containing the ids of the patches + applied to the MPFR library (contents of the ‘PATCHES’ file), + separated by spaces. Note: If the program has been compiled with + an older MPFR version and is dynamically linked with a new MPFR + library version, the identifiers of the patches applied to the old + (compile-time) MPFR version are not available (however this + information should not have much interest in general). + + -- Function: int mpfr_buildopt_tls_p (void) + Return a non-zero value if MPFR was compiled as thread safe using + compiler-level Thread Local Storage (that is, MPFR was built with + the ‘--enable-thread-safe’ configure option, see ‘INSTALL’ file), + return zero otherwise. + + -- Function: int mpfr_buildopt_decimal_p (void) + Return a non-zero value if MPFR was compiled with decimal float + support (that is, MPFR was built with the ‘--enable-decimal-float’ + configure option), return zero otherwise. + + -- Function: int mpfr_buildopt_gmpinternals_p (void) + Return a non-zero value if MPFR was compiled with GMP internals + (that is, MPFR was built with either ‘--with-gmp-build’ or + ‘--enable-gmp-internals’ configure option), return zero otherwise. + + -- Function: const char * mpfr_buildopt_tune_case (void) + Return a string saying which thresholds file has been used at + compile time. This file is normally selected from the processor + type. + + +File: mpfr.info, Node: Exception Related Functions, Next: Compatibility with MPF, Prev: Miscellaneous Functions, Up: MPFR Interface + +5.13 Exception Related Functions +================================ + + -- Function: mpfr_exp_t mpfr_get_emin (void) + -- Function: mpfr_exp_t mpfr_get_emax (void) + Return the (current) smallest and largest exponents allowed for a + floating-point variable. The smallest positive value of a + floating-point variable is one half times 2 raised to the smallest + exponent and the largest value has the form (1 - epsilon) times 2 + raised to the largest exponent, where epsilon depends on the + precision of the considered variable. + + -- Function: int mpfr_set_emin (mpfr_exp_t EXP) + -- Function: int mpfr_set_emax (mpfr_exp_t EXP) + Set the smallest and largest exponents allowed for a floating-point + variable. Return a non-zero value when EXP is not in the range + accepted by the implementation (in that case the smallest or + largest exponent is not changed), and zero otherwise. If the user + changes the exponent range, it is her/his responsibility to check + that all current floating-point variables are in the new allowed + range (for example using ‘mpfr_check_range’), otherwise the + subsequent behavior will be undefined, in the sense of the ISO C + standard. + + -- Function: mpfr_exp_t mpfr_get_emin_min (void) + -- Function: mpfr_exp_t mpfr_get_emin_max (void) + -- Function: mpfr_exp_t mpfr_get_emax_min (void) + -- Function: mpfr_exp_t mpfr_get_emax_max (void) + Return the minimum and maximum of the exponents allowed for + ‘mpfr_set_emin’ and ‘mpfr_set_emax’ respectively. These values are + implementation dependent, thus a program using + ‘mpfr_set_emax(mpfr_get_emax_max())’ or + ‘mpfr_set_emin(mpfr_get_emin_min())’ may not be portable. + + -- Function: int mpfr_check_range (mpfr_t X, int T, mpfr_rnd_t RND) + This function assumes that X is the correctly-rounded value of some + real value Y in the direction RND and some extended exponent range, + and that T is the corresponding *note ternary value::. For + example, one performed ‘t = mpfr_log (x, u, rnd)’, and Y is the + exact logarithm of U. Thus T is negative if X is smaller than Y, + positive if X is larger than Y, and zero if X equals Y. This + function modifies X if needed to be in the current range of + acceptable values: It generates an underflow or an overflow if the + exponent of X is outside the current allowed range; the value of T + may be used to avoid a double rounding. This function returns zero + if the new value of X equals the exact one Y, a positive value if + that new value is larger than Y, and a negative value if it is + smaller than Y. Note that unlike most functions, the new result X + is compared to the (unknown) exact one Y, not the input value X, + i.e., the ternary value is propagated. + + Note: If X is an infinity and T is different from zero (i.e., if + the rounded result is an inexact infinity), then the overflow flag + is set. This is useful because ‘mpfr_check_range’ is typically + called (at least in MPFR functions) after restoring the flags that + could have been set due to internal computations. + + -- Function: int mpfr_subnormalize (mpfr_t X, int T, mpfr_rnd_t RND) + This function rounds X emulating subnormal number arithmetic: if X + is outside the subnormal exponent range, it just propagates the + *note ternary value:: T; otherwise, it rounds X to precision + ‘EXP(x)-emin+1’ according to rounding mode RND and previous ternary + value T, avoiding double rounding problems. More precisely in the + subnormal domain, denoting by E the value of ‘emin’, X is rounded + in fixed-point arithmetic to an integer multiple of two to the + power E−1; as a consequence, 1.5 multiplied by two to the power E−1 + when T is zero is rounded to two to the power E with rounding to + nearest. + + ‘PREC(x)’ is not modified by this function. RND and T must be the + rounding mode and the returned ternary value used when computing X + (as in ‘mpfr_check_range’). The subnormal exponent range is from + ‘emin’ to ‘emin+PREC(x)-1’. If the result cannot be represented in + the current exponent range (due to a too small ‘emax’), the + behavior is undefined. Note that unlike most functions, the result + is compared to the exact one, not the input value X, i.e., the + ternary value is propagated. + + As usual, if the returned ternary value is non zero, the inexact + flag is set. Moreover, if a second rounding occurred (because the + input X was in the subnormal range), the underflow flag is set. + + This is an example of how to emulate binary double IEEE 754 +arithmetic (binary64 in IEEE 754-2008) using MPFR: + + { + mpfr_t xa, xb; int i; volatile double a, b; + + mpfr_set_default_prec (53); + mpfr_set_emin (-1073); mpfr_set_emax (1024); + + mpfr_init (xa); mpfr_init (xb); + + b = 34.3; mpfr_set_d (xb, b, MPFR_RNDN); + a = 0x1.1235P-1021; mpfr_set_d (xa, a, MPFR_RNDN); + + a /= b; + i = mpfr_div (xa, xa, xb, MPFR_RNDN); + i = mpfr_subnormalize (xa, i, MPFR_RNDN); /* new ternary value */ + + mpfr_clear (xa); mpfr_clear (xb); + } + + Warning: this emulates a double IEEE 754 arithmetic with correct +rounding in the subnormal range, which may not be the case for your +hardware. + + -- Function: void mpfr_clear_underflow (void) + -- Function: void mpfr_clear_overflow (void) + -- Function: void mpfr_clear_divby0 (void) + -- Function: void mpfr_clear_nanflag (void) + -- Function: void mpfr_clear_inexflag (void) + -- Function: void mpfr_clear_erangeflag (void) + Clear the underflow, overflow, divide-by-zero, invalid, inexact and + _erange_ flags. + + -- Function: void mpfr_set_underflow (void) + -- Function: void mpfr_set_overflow (void) + -- Function: void mpfr_set_divby0 (void) + -- Function: void mpfr_set_nanflag (void) + -- Function: void mpfr_set_inexflag (void) + -- Function: void mpfr_set_erangeflag (void) + Set the underflow, overflow, divide-by-zero, invalid, inexact and + _erange_ flags. + + -- Function: void mpfr_clear_flags (void) + Clear all global flags (underflow, overflow, divide-by-zero, + invalid, inexact, _erange_). + + -- Function: int mpfr_underflow_p (void) + -- Function: int mpfr_overflow_p (void) + -- Function: int mpfr_divby0_p (void) + -- Function: int mpfr_nanflag_p (void) + -- Function: int mpfr_inexflag_p (void) + -- Function: int mpfr_erangeflag_p (void) + Return the corresponding (underflow, overflow, divide-by-zero, + invalid, inexact, _erange_) flag, which is non-zero iff the flag is + set. + + +File: mpfr.info, Node: Compatibility with MPF, Next: Custom Interface, Prev: Exception Related Functions, Up: MPFR Interface + +5.14 Compatibility With MPF +=========================== + +A header file ‘mpf2mpfr.h’ is included in the distribution of MPFR for +compatibility with the GNU MP class MPF. By inserting the following two +lines after the ‘#include <gmp.h>’ line, + #include <mpfr.h> + #include <mpf2mpfr.h> +any program written for MPF can be compiled directly with MPFR without +any changes (except the ‘gmp_printf’ functions will not work for +arguments of type ‘mpfr_t’). All operations are then performed with the +default MPFR rounding mode, which can be reset with +‘mpfr_set_default_rounding_mode’. + + Warning: the ‘mpf_init’ and ‘mpf_init2’ functions initialize to zero, +whereas the corresponding MPFR functions initialize to NaN: this is +useful to detect uninitialized values, but is slightly incompatible with +MPF. + + -- Function: void mpfr_set_prec_raw (mpfr_t X, mpfr_prec_t PREC) + Reset the precision of X to be *exactly* PREC bits. The only + difference with ‘mpfr_set_prec’ is that PREC is assumed to be small + enough so that the significand fits into the current allocated + memory space for X. Otherwise the behavior is undefined. + + -- Function: int mpfr_eq (mpfr_t OP1, mpfr_t OP2, unsigned long int + OP3) + Return non-zero if OP1 and OP2 are both non-zero ordinary numbers + with the same exponent and the same first OP3 bits, both zero, or + both infinities of the same sign. Return zero otherwise. This + function is defined for compatibility with MPF, we do not recommend + to use it otherwise. Do not use it either if you want to know + whether two numbers are close to each other; for instance, 1.011111 + and 1.100000 are regarded as different for any value of OP3 larger + than 1. + + -- Function: void mpfr_reldiff (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, + mpfr_rnd_t RND) + Compute the relative difference between OP1 and OP2 and store the + result in ROP. This function does not guarantee the correct + rounding on the relative difference; it just computes + |OP1-OP2|/OP1, using the precision of ROP and the rounding mode RND + for all operations. + + -- Function: int mpfr_mul_2exp (mpfr_t ROP, mpfr_t OP1, unsigned long + int OP2, mpfr_rnd_t RND) + -- Function: int mpfr_div_2exp (mpfr_t ROP, mpfr_t OP1, unsigned long + int OP2, mpfr_rnd_t RND) + These functions are identical to ‘mpfr_mul_2ui’ and ‘mpfr_div_2ui’ + respectively. These functions are only kept for compatibility with + MPF, one should prefer ‘mpfr_mul_2ui’ and ‘mpfr_div_2ui’ otherwise. + + +File: mpfr.info, Node: Custom Interface, Next: Internals, Prev: Compatibility with MPF, Up: MPFR Interface + +5.15 Custom Interface +===================== + +Some applications use a stack to handle the memory and their objects. +However, the MPFR memory design is not well suited for such a thing. So +that such applications are able to use MPFR, an auxiliary memory +interface has been created: the Custom Interface. + + The following interface allows one to use MPFR in two ways: + + • Either directly store a floating-point number as a ‘mpfr_t’ on the + stack. + + • Either store its own representation on the stack and construct a + new temporary ‘mpfr_t’ each time it is needed. + + Nothing has to be done to destroy the floating-point numbers except +garbaging the used memory: all the memory management (allocating, +destroying, garbaging) is left to the application. + + Each function in this interface is also implemented as a macro for +efficiency reasons: for example ‘mpfr_custom_init (s, p)’ uses the +macro, while ‘(mpfr_custom_init) (s, p)’ uses the function. + + Note 1: MPFR functions may still initialize temporary floating-point +numbers using ‘mpfr_init’ and similar functions. See Custom Allocation +(GNU MP). + + Note 2: MPFR functions may use the cached functions (‘mpfr_const_pi’ +for example), even if they are not explicitly called. You have to call +‘mpfr_free_cache’ each time you garbage the memory iff ‘mpfr_init’, +through GMP Custom Allocation, allocates its memory on the application +stack. + + -- Function: size_t mpfr_custom_get_size (mpfr_prec_t PREC) + Return the needed size in bytes to store the significand of a + floating-point number of precision PREC. + + -- Function: void mpfr_custom_init (void *SIGNIFICAND, mpfr_prec_t + PREC) + Initialize a significand of precision PREC, where SIGNIFICAND must + be an area of ‘mpfr_custom_get_size (prec)’ bytes at least and be + suitably aligned for an array of ‘mp_limb_t’ (GMP type, *note + Internals::). + + -- Function: void mpfr_custom_init_set (mpfr_t X, int KIND, mpfr_exp_t + EXP, mpfr_prec_t PREC, void *SIGNIFICAND) + Perform a dummy initialization of a ‘mpfr_t’ and set it to: + • if ‘ABS(kind) == MPFR_NAN_KIND’, X is set to NaN; + • if ‘ABS(kind) == MPFR_INF_KIND’, X is set to the infinity of + sign ‘sign(kind)’; + • if ‘ABS(kind) == MPFR_ZERO_KIND’, X is set to the zero of sign + ‘sign(kind)’; + • if ‘ABS(kind) == MPFR_REGULAR_KIND’, X is set to a regular + number: ‘x = sign(kind)*significand*2^exp’. + In all cases, it uses SIGNIFICAND directly for further computing + involving X. It will not allocate anything. A floating-point + number initialized with this function cannot be resized using + ‘mpfr_set_prec’ or ‘mpfr_prec_round’, or cleared using + ‘mpfr_clear’! The SIGNIFICAND must have been initialized with + ‘mpfr_custom_init’ using the same precision PREC. + + -- Function: int mpfr_custom_get_kind (mpfr_t X) + Return the current kind of a ‘mpfr_t’ as created by + ‘mpfr_custom_init_set’. The behavior of this function for any + ‘mpfr_t’ not initialized with ‘mpfr_custom_init_set’ is undefined. + + -- Function: void * mpfr_custom_get_significand (mpfr_t X) + Return a pointer to the significand used by a ‘mpfr_t’ initialized + with ‘mpfr_custom_init_set’. The behavior of this function for any + ‘mpfr_t’ not initialized with ‘mpfr_custom_init_set’ is undefined. + + -- Function: mpfr_exp_t mpfr_custom_get_exp (mpfr_t X) + Return the exponent of X, assuming that X is a non-zero ordinary + number. The return value for NaN, Infinity or zero is unspecified + but does not produce any trap. The behavior of this function for + any ‘mpfr_t’ not initialized with ‘mpfr_custom_init_set’ is + undefined. + + -- Function: void mpfr_custom_move (mpfr_t X, void *NEW_POSITION) + Inform MPFR that the significand of X has moved due to a garbage + collect and update its new position to ‘new_position’. However the + application has to move the significand and the ‘mpfr_t’ itself. + The behavior of this function for any ‘mpfr_t’ not initialized with + ‘mpfr_custom_init_set’ is undefined. + + +File: mpfr.info, Node: Internals, Prev: Custom Interface, Up: MPFR Interface + +5.16 Internals +============== + +A "limb" means the part of a multi-precision number that fits in a +single word. Usually a limb contains 32 or 64 bits. The C data type +for a limb is ‘mp_limb_t’. + + The ‘mpfr_t’ type is internally defined as a one-element array of a +structure, and ‘mpfr_ptr’ is the C data type representing a pointer to +this structure. The ‘mpfr_t’ type consists of four fields: + + • The ‘_mpfr_prec’ field is used to store the precision of the + variable (in bits); this is not less than ‘MPFR_PREC_MIN’. + + • The ‘_mpfr_sign’ field is used to store the sign of the variable. + + • The ‘_mpfr_exp’ field stores the exponent. An exponent of 0 means + a radix point just above the most significant limb. Non-zero + values n are a multiplier 2^n relative to that point. A NaN, an + infinity and a zero are indicated by special values of the exponent + field. + + • Finally, the ‘_mpfr_d’ field is a pointer to the limbs, least + significant limbs stored first. The number of limbs in use is + controlled by ‘_mpfr_prec’, namely + ceil(‘_mpfr_prec’/‘mp_bits_per_limb’). Non-singular (i.e., + different from NaN, Infinity or zero) values always have the most + significant bit of the most significant limb set to 1. When the + precision does not correspond to a whole number of limbs, the + excess bits at the low end of the data are zeros. + + +File: mpfr.info, Node: API Compatibility, Next: Contributors, Prev: MPFR Interface, Up: Top + +6 API Compatibility +******************* + +The goal of this section is to describe some API changes that occurred +from one version of MPFR to another, and how to write code that can be +compiled and run with older MPFR versions. The minimum MPFR version +that is considered here is 2.2.0 (released on 20 September 2005). + + API changes can only occur between major or minor versions. Thus the +patchlevel (the third number in the MPFR version) will be ignored in the +following. If a program does not use MPFR internals, changes in the +behavior between two versions differing only by the patchlevel should +only result from what was regarded as a bug or unspecified behavior. + + As a general rule, a program written for some MPFR version should +work with later versions, possibly except at a new major version, where +some features (described as obsolete for some time) can be removed. In +such a case, a failure should occur during compilation or linking. If a +result becomes incorrect because of such a change, please look at the +various changes below (they are minimal, and most software should be +unaffected), at the FAQ and at the MPFR web page for your version (a bug +could have been introduced and be already fixed); and if the problem is +not mentioned, please send us a bug report (*note Reporting Bugs::). + + However, a program written for the current MPFR version (as +documented by this manual) may not necessarily work with previous +versions of MPFR. This section should help developers to write portable +code. + + Note: Information given here may be incomplete. API changes are also +described in the NEWS file (for each version, instead of being +classified like here), together with other changes. + +* Menu: + +* Type and Macro Changes:: +* Added Functions:: +* Changed Functions:: +* Removed Functions:: +* Other Changes:: + + +File: mpfr.info, Node: Type and Macro Changes, Next: Added Functions, Prev: API Compatibility, Up: API Compatibility + +6.1 Type and Macro Changes +========================== + +The official type for exponent values changed from ‘mp_exp_t’ to +‘mpfr_exp_t’ in MPFR 3.0. The type ‘mp_exp_t’ will remain available as +it comes from GMP (with a different meaning). These types are currently +the same (‘mpfr_exp_t’ is defined as ‘mp_exp_t’ with ‘typedef’), so that +programs can still use ‘mp_exp_t’; but this may change in the future. +Alternatively, using the following code after including ‘mpfr.h’ will +work with official MPFR versions, as ‘mpfr_exp_t’ was never defined in +MPFR 2.x: + #if MPFR_VERSION_MAJOR < 3 + typedef mp_exp_t mpfr_exp_t; + #endif + + The official types for precision values and for rounding modes +respectively changed from ‘mp_prec_t’ and ‘mp_rnd_t’ to ‘mpfr_prec_t’ +and ‘mpfr_rnd_t’ in MPFR 3.0. This change was actually done a long time +ago in MPFR, at least since MPFR 2.2.0, with the following code in +‘mpfr.h’: + #ifndef mp_rnd_t + # define mp_rnd_t mpfr_rnd_t + #endif + #ifndef mp_prec_t + # define mp_prec_t mpfr_prec_t + #endif + This means that it is safe to use the new official types +‘mpfr_prec_t’ and ‘mpfr_rnd_t’ in your programs. The types ‘mp_prec_t’ +and ‘mp_rnd_t’ (defined in MPFR only) may be removed in the future, as +the prefix ‘mp_’ is reserved by GMP. + + The precision type ‘mpfr_prec_t’ (‘mp_prec_t’) was unsigned before +MPFR 3.0; it is now signed. ‘MPFR_PREC_MAX’ has not changed, though. +Indeed the MPFR code requires that ‘MPFR_PREC_MAX’ be representable in +the exponent type, which may have the same size as ‘mpfr_prec_t’ but has +always been signed. The consequence is that valid code that does not +assume anything about the signedness of ‘mpfr_prec_t’ should work with +past and new MPFR versions. This change was useful as the use of +unsigned types tends to convert signed values to unsigned ones in +expressions due to the usual arithmetic conversions, which can yield +incorrect results if a negative value is converted in such a way. +Warning! A program assuming (intentionally or not) that ‘mpfr_prec_t’ +is signed may be affected by this problem when it is built and run +against MPFR 2.x. + + The rounding modes ‘GMP_RNDx’ were renamed to ‘MPFR_RNDx’ in MPFR +3.0. However the old names ‘GMP_RNDx’ have been kept for compatibility +(this might change in future versions), using: + #define GMP_RNDN MPFR_RNDN + #define GMP_RNDZ MPFR_RNDZ + #define GMP_RNDU MPFR_RNDU + #define GMP_RNDD MPFR_RNDD + The rounding mode “round away from zero” (‘MPFR_RNDA’) was added in +MPFR 3.0 (however no rounding mode ‘GMP_RNDA’ exists). + + +File: mpfr.info, Node: Added Functions, Next: Changed Functions, Prev: Type and Macro Changes, Up: API Compatibility + +6.2 Added Functions +=================== + +We give here in alphabetical order the functions that were added after +MPFR 2.2, and in which MPFR version. + + • ‘mpfr_add_d’ in MPFR 2.4. + + • ‘mpfr_ai’ in MPFR 3.0 (incomplete, experimental). + + • ‘mpfr_asprintf’ in MPFR 2.4. + + • ‘mpfr_buildopt_decimal_p’ and ‘mpfr_buildopt_tls_p’ in MPFR 3.0. + + • ‘mpfr_buildopt_gmpinternals_p’ and ‘mpfr_buildopt_tune_case’ in + MPFR 3.1. + + • ‘mpfr_clear_divby0’ in MPFR 3.1 (new divide-by-zero exception). + + • ‘mpfr_copysign’ in MPFR 2.3. Note: MPFR 2.2 had a ‘mpfr_copysign’ + function that was available, but not documented, and with a slight + difference in the semantics (when the second input operand is a + NaN). + + • ‘mpfr_custom_get_significand’ in MPFR 3.0. This function was named + ‘mpfr_custom_get_mantissa’ in previous versions; + ‘mpfr_custom_get_mantissa’ is still available via a macro in + ‘mpfr.h’: + #define mpfr_custom_get_mantissa mpfr_custom_get_significand + Thus code that needs to work with both MPFR 2.x and MPFR 3.x should + use ‘mpfr_custom_get_mantissa’. + + • ‘mpfr_d_div’ and ‘mpfr_d_sub’ in MPFR 2.4. + + • ‘mpfr_digamma’ in MPFR 3.0. + + • ‘mpfr_divby0_p’ in MPFR 3.1 (new divide-by-zero exception). + + • ‘mpfr_div_d’ in MPFR 2.4. + + • ‘mpfr_fmod’ in MPFR 2.4. + + • ‘mpfr_fms’ in MPFR 2.3. + + • ‘mpfr_fprintf’ in MPFR 2.4. + + • ‘mpfr_frexp’ in MPFR 3.1. + + • ‘mpfr_get_flt’ in MPFR 3.0. + + • ‘mpfr_get_patches’ in MPFR 2.3. + + • ‘mpfr_get_z_2exp’ in MPFR 3.0. This function was named + ‘mpfr_get_z_exp’ in previous versions; ‘mpfr_get_z_exp’ is still + available via a macro in ‘mpfr.h’: + #define mpfr_get_z_exp mpfr_get_z_2exp + Thus code that needs to work with both MPFR 2.x and MPFR 3.x should + use ‘mpfr_get_z_exp’. + + • ‘mpfr_grandom’ in MPFR 3.1. + + • ‘mpfr_j0’, ‘mpfr_j1’ and ‘mpfr_jn’ in MPFR 2.3. + + • ‘mpfr_lgamma’ in MPFR 2.3. + + • ‘mpfr_li2’ in MPFR 2.4. + + • ‘mpfr_min_prec’ in MPFR 3.0. + + • ‘mpfr_modf’ in MPFR 2.4. + + • ‘mpfr_mul_d’ in MPFR 2.4. + + • ‘mpfr_printf’ in MPFR 2.4. + + • ‘mpfr_rec_sqrt’ in MPFR 2.4. + + • ‘mpfr_regular_p’ in MPFR 3.0. + + • ‘mpfr_remainder’ and ‘mpfr_remquo’ in MPFR 2.3. + + • ‘mpfr_set_divby0’ in MPFR 3.1 (new divide-by-zero exception). + + • ‘mpfr_set_flt’ in MPFR 3.0. + + • ‘mpfr_set_z_2exp’ in MPFR 3.0. + + • ‘mpfr_set_zero’ in MPFR 3.0. + + • ‘mpfr_setsign’ in MPFR 2.3. + + • ‘mpfr_signbit’ in MPFR 2.3. + + • ‘mpfr_sinh_cosh’ in MPFR 2.4. + + • ‘mpfr_snprintf’ and ‘mpfr_sprintf’ in MPFR 2.4. + + • ‘mpfr_sub_d’ in MPFR 2.4. + + • ‘mpfr_urandom’ in MPFR 3.0. + + • ‘mpfr_vasprintf’, ‘mpfr_vfprintf’, ‘mpfr_vprintf’, ‘mpfr_vsprintf’ + and ‘mpfr_vsnprintf’ in MPFR 2.4. + + • ‘mpfr_y0’, ‘mpfr_y1’ and ‘mpfr_yn’ in MPFR 2.3. + + • ‘mpfr_z_sub’ in MPFR 3.1. + + +File: mpfr.info, Node: Changed Functions, Next: Removed Functions, Prev: Added Functions, Up: API Compatibility + +6.3 Changed Functions +===================== + +The following functions have changed after MPFR 2.2. Changes can affect +the behavior of code written for some MPFR version when built and run +against another MPFR version (older or newer), as described below. + + • ‘mpfr_check_range’ changed in MPFR 2.3.2 and MPFR 2.4. If the + value is an inexact infinity, the overflow flag is now set (in case + it was lost), while it was previously left unchanged. This is + really what is expected in practice (and what the MPFR code was + expecting), so that the previous behavior was regarded as a bug. + Hence the change in MPFR 2.3.2. + + • ‘mpfr_get_f’ changed in MPFR 3.0. This function was returning + zero, except for NaN and Inf, which do not exist in MPF. The + _erange_ flag is now set in these cases, and ‘mpfr_get_f’ now + returns the usual ternary value. + + • ‘mpfr_get_si’, ‘mpfr_get_sj’, ‘mpfr_get_ui’ and ‘mpfr_get_uj’ + changed in MPFR 3.0. In previous MPFR versions, the cases where + the _erange_ flag is set were unspecified. + + • ‘mpfr_get_z’ changed in MPFR 3.0. The return type was ‘void’; it + is now ‘int’, and the usual ternary value is returned. Thus + programs that need to work with both MPFR 2.x and 3.x must not use + the return value. Even in this case, C code using ‘mpfr_get_z’ as + the second or third term of a conditional operator may also be + affected. For instance, the following is correct with MPFR 3.0, + but not with MPFR 2.x: + bool ? mpfr_get_z(...) : mpfr_add(...); + On the other hand, the following is correct with MPFR 2.x, but not + with MPFR 3.0: + bool ? mpfr_get_z(...) : (void) mpfr_add(...); + Portable code should cast ‘mpfr_get_z(...)’ to ‘void’ to use the + type ‘void’ for both terms of the conditional operator, as in: + bool ? (void) mpfr_get_z(...) : (void) mpfr_add(...); + Alternatively, ‘if ... else’ can be used instead of the conditional + operator. + + Moreover the cases where the _erange_ flag is set were unspecified + in MPFR 2.x. + + • ‘mpfr_get_z_exp’ changed in MPFR 3.0. In previous MPFR versions, + the cases where the _erange_ flag is set were unspecified. Note: + this function has been renamed to ‘mpfr_get_z_2exp’ in MPFR 3.0, + but ‘mpfr_get_z_exp’ is still available for compatibility reasons. + + • ‘mpfr_strtofr’ changed in MPFR 2.3.1 and MPFR 2.4. This was + actually a bug fix since the code and the documentation did not + match. But both were changed in order to have a more consistent + and useful behavior. The main changes in the code are as follows. + The binary exponent is now accepted even without the ‘0b’ or ‘0x’ + prefix. Data corresponding to NaN can now have an optional sign + (such data were previously invalid). + + • ‘mpfr_strtofr’ changed in MPFR 3.0. This function now accepts + bases from 37 to 62 (no changes for the other bases). Note: if an + unsupported base is provided to this function, the behavior is + undefined; more precisely, in MPFR 2.3.1 and later, providing an + unsupported base yields an assertion failure (this behavior may + change in the future). + + • ‘mpfr_subnormalize’ changed in MPFR 3.1. This was actually + regarded as a bug fix. The ‘mpfr_subnormalize’ implementation up + to MPFR 3.0.0 did not change the flags. In particular, it did not + follow the generic rule concerning the inexact flag (and no special + behavior was specified). The case of the underflow flag was more a + lack of specification. + + • ‘mpfr_urandom’ and ‘mpfr_urandomb’ changed in MPFR 3.1. Their + behavior no longer depends on the platform (assuming this is also + true for GMP’s random generator, which is not the case between GMP + 4.1 and 4.2 if ‘gmp_randinit_default’ is used). As a consequence, + the returned values can be different between MPFR 3.1 and previous + MPFR versions. Note: as the reproducibility of these functions was + not specified before MPFR 3.1, the MPFR 3.1 behavior is _not_ + regarded as backward incompatible with previous versions. + + +File: mpfr.info, Node: Removed Functions, Next: Other Changes, Prev: Changed Functions, Up: API Compatibility + +6.4 Removed Functions +===================== + +Functions ‘mpfr_random’ and ‘mpfr_random2’ have been removed in MPFR 3.0 +(this only affects old code built against MPFR 3.0 or later). (The +function ‘mpfr_random’ had been deprecated since at least MPFR 2.2.0, +and ‘mpfr_random2’ since MPFR 2.4.0.) + + +File: mpfr.info, Node: Other Changes, Prev: Removed Functions, Up: API Compatibility + +6.5 Other Changes +================= + +For users of a C++ compiler, the way how the availability of ‘intmax_t’ +is detected has changed in MPFR 3.0. In MPFR 2.x, if a macro ‘INTMAX_C’ +or ‘UINTMAX_C’ was defined (e.g. when the ‘__STDC_CONSTANT_MACROS’ +macro had been defined before ‘<stdint.h>’ or ‘<inttypes.h>’ has been +included), ‘intmax_t’ was assumed to be defined. However this was not +always the case (more precisely, ‘intmax_t’ can be defined only in the +namespace ‘std’, as with Boost), so that compilations could fail. Thus +the check for ‘INTMAX_C’ or ‘UINTMAX_C’ is now disabled for C++ +compilers, with the following consequences: + + • Programs written for MPFR 2.x that need ‘intmax_t’ may no longer be + compiled against MPFR 3.0: a ‘#define MPFR_USE_INTMAX_T’ may be + necessary before ‘mpfr.h’ is included. + + • The compilation of programs that work with MPFR 3.0 may fail with + MPFR 2.x due to the problem described above. Workarounds are + possible, such as defining ‘intmax_t’ and ‘uintmax_t’ in the global + namespace, though this is not clean. + + The divide-by-zero exception is new in MPFR 3.1. However it should +not introduce incompatible changes for programs that strictly follow the +MPFR API since the exception can only be seen via new functions. + + As of MPFR 3.1, the ‘mpfr.h’ header can be included several times, +while still supporting optional functions (*note Headers and +Libraries::). + + +File: mpfr.info, Node: Contributors, Next: References, Prev: API Compatibility, Up: Top + +Contributors +************ + +The main developers of MPFR are Guillaume Hanrot, Vincent Lefèvre, +Patrick Pélissier, Philippe Théveny and Paul Zimmermann. + + Sylvie Boldo from ENS-Lyon, France, contributed the functions +‘mpfr_agm’ and ‘mpfr_log’. Sylvain Chevillard contributed the ‘mpfr_ai’ +function. David Daney contributed the hyperbolic and inverse hyperbolic +functions, the base-2 exponential, and the factorial function. Alain +Delplanque contributed the new version of the ‘mpfr_get_str’ function. +Mathieu Dutour contributed the functions ‘mpfr_acos’, ‘mpfr_asin’ and +‘mpfr_atan’, and a previous version of ‘mpfr_gamma’. Laurent Fousse +contributed the ‘mpfr_sum’ function. Emmanuel Jeandel, from ENS-Lyon +too, contributed the generic hypergeometric code, as well as the +internal function ‘mpfr_exp3’, a first implementation of the sine and +cosine, and improved versions of ‘mpfr_const_log2’ and ‘mpfr_const_pi’. +Ludovic Meunier helped in the design of the ‘mpfr_erf’ code. Jean-Luc +Rémy contributed the ‘mpfr_zeta’ code. Fabrice Rouillier contributed +the ‘mpfr_xxx_z’ and ‘mpfr_xxx_q’ functions, and helped to the Microsoft +Windows porting. Damien Stehlé contributed the ‘mpfr_get_ld_2exp’ +function. + + We would like to thank Jean-Michel Muller and Joris van der Hoeven +for very fruitful discussions at the beginning of that project, Torbjörn +Granlund and Kevin Ryde for their help about design issues, and Nathalie +Revol for her careful reading of a previous version of this +documentation. In particular Kevin Ryde did a tremendous job for the +portability of MPFR in 2002-2004. + + The development of the MPFR library would not have been possible +without the continuous support of INRIA, and of the LORIA (Nancy, +France) and LIP (Lyon, France) laboratories. In particular the main +authors were or are members of the PolKA, Spaces, Cacao and Caramel +project-teams at LORIA and of the Arénaire and AriC project-teams at +LIP. This project was started during the Fiable (reliable in French) +action supported by INRIA, and continued during the AOC action. The +development of MPFR was also supported by a grant (202F0659 00 MPN 121) +from the Conseil Régional de Lorraine in 2002, from INRIA by an +"associate engineer" grant (2003-2005), an "opération de développement +logiciel" grant (2007-2009), and the post-doctoral grant of Sylvain +Chevillard in 2009-2010. The MPFR-MPC workshop in June 2012 was partly +supported by the ERC grant ANTICS of Andreas Enge. + + +File: mpfr.info, Node: References, Next: GNU Free Documentation License, Prev: Contributors, Up: Top + +References +********** + + • Richard Brent and Paul Zimmermann, "Modern Computer Arithmetic", + Cambridge University Press (to appear), also available from the + authors’ web pages. + + • Laurent Fousse, Guillaume Hanrot, Vincent Lefèvre, Patrick + Pélissier and Paul Zimmermann, "MPFR: A Multiple-Precision Binary + Floating-Point Library With Correct Rounding", ACM Transactions on + Mathematical Software, volume 33, issue 2, article 13, 15 pages, + 2007, <http://doi.acm.org/10.1145/1236463.1236468>. + + • Torbjörn Granlund, "GNU MP: The GNU Multiple Precision Arithmetic + Library", version 5.0.1, 2010, <http://gmplib.org>. + + • IEEE standard for binary floating-point arithmetic, Technical + Report ANSI-IEEE Standard 754-1985, New York, 1985. Approved March + 21, 1985: IEEE Standards Board; approved July 26, 1985: American + National Standards Institute, 18 pages. + + • IEEE Standard for Floating-Point Arithmetic, ANSI-IEEE Standard + 754-2008, 2008. Revision of ANSI-IEEE Standard 754-1985, approved + June 12, 2008: IEEE Standards Board, 70 pages. + + • Donald E. Knuth, "The Art of Computer Programming", vol 2, + "Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981. + + • Jean-Michel Muller, "Elementary Functions, Algorithms and + Implementation", Birkhäuser, Boston, 2nd edition, 2006. + + • Jean-Michel Muller, Nicolas Brisebarre, Florent de Dinechin, + Claude-Pierre Jeannerod, Vincent Lefèvre, Guillaume Melquiond, + Nathalie Revol, Damien Stehlé and Serge Torrès, "Handbook of + Floating-Point Arithmetic", Birkhäuser, Boston, 2009. + + +File: mpfr.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: References, Up: Top + +Appendix A GNU Free Documentation License +***************************************** + + Version 1.2, November 2002 + + Copyright © 2000,2001,2002 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of “copyleft”, which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + “Document”, below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as “you”. You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A “Modified Version” of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A “Secondary Section” is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document’s overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The “Invariant Sections” are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The “Cover Texts” are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A “Transparent” copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + “Transparent” is called “Opaque”. + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The “Title Page” means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, “Title + Page” means the text near the most prominent appearance of the + work’s title, preceding the beginning of the body of the text. + + A section “Entitled XYZ” means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) + To “Preserve the Title” of such a section when you modify the + Document means that it remains a section “Entitled XYZ” according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document’s license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document’s + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled “History”, Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled “History” in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + “History” section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled “Acknowledgements” or “Dedications”, + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled “Endorsements”. Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + “Endorsements” or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version’s + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled “Endorsements”, provided it contains + nothing but endorsements of your Modified Version by various + parties—for example, statements of peer review or that the text has + been approved by an organization as the authoritative definition of + a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + “History” in the various original documents, forming one section + Entitled “History”; likewise combine any sections Entitled + “Acknowledgements”, and any sections Entitled “Dedications”. You + must delete all sections Entitled “Endorsements.” + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an “aggregate” if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation’s users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document’s Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled “Acknowledgements”, + “Dedications”, or “History”, the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided for under this License. Any other + attempt to copy, modify, sublicense or distribute the Document is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses terminated + so long as such parties remain in full compliance. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + <http://www.gnu.org/copyleft/>. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License “or any later version” applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. + +A.1 ADDENDUM: How to Use This License For Your Documents +======================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the “with...Texts.” line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: mpfr.info, Node: Concept Index, Next: Function and Type Index, Prev: GNU Free Documentation License, Up: Top + +Concept Index +************* + + +* Menu: + +* Accuracy: MPFR Interface. (line 25) +* Arithmetic functions: Basic Arithmetic Functions. + (line 3) +* Assignment functions: Assignment Functions. (line 3) +* Basic arithmetic functions: Basic Arithmetic Functions. + (line 3) +* Combined initialization and assignment functions: Combined Initialization and Assignment Functions. + (line 3) +* Comparison functions: Comparison Functions. (line 3) +* Compatibility with MPF: Compatibility with MPF. + (line 3) +* Conditions for copying MPFR: Copying. (line 6) +* Conversion functions: Conversion Functions. (line 3) +* Copying conditions: Copying. (line 6) +* Custom interface: Custom Interface. (line 3) +* Exception related functions: Exception Related Functions. + (line 3) +* Float arithmetic functions: Basic Arithmetic Functions. + (line 3) +* Float comparisons functions: Comparison Functions. (line 3) +* Float functions: MPFR Interface. (line 6) +* Float input and output functions: Input and Output Functions. + (line 3) +* Float output functions: Formatted Output Functions. + (line 3) +* Floating-point functions: MPFR Interface. (line 6) +* Floating-point number: Nomenclature and Types. + (line 6) +* GNU Free Documentation License: GNU Free Documentation License. + (line 6) +* GNU Free Documentation License <1>: GNU Free Documentation License. + (line 6) +* I/O functions: Input and Output Functions. + (line 3) +* I/O functions <1>: Formatted Output Functions. + (line 3) +* Initialization functions: Initialization Functions. + (line 3) +* Input functions: Input and Output Functions. + (line 3) +* Installation: Installing MPFR. (line 6) +* Integer related functions: Integer Related Functions. + (line 3) +* Internals: Internals. (line 3) +* ‘intmax_t’: Headers and Libraries. + (line 22) +* ‘inttypes.h’: Headers and Libraries. + (line 22) +* ‘libmpfr’: Headers and Libraries. + (line 50) +* Libraries: Headers and Libraries. + (line 50) +* Libtool: Headers and Libraries. + (line 56) +* Limb: Internals. (line 6) +* Linking: Headers and Libraries. + (line 50) +* Miscellaneous float functions: Miscellaneous Functions. + (line 3) +* ‘mpfr.h’: Headers and Libraries. + (line 6) +* Output functions: Input and Output Functions. + (line 3) +* Output functions <1>: Formatted Output Functions. + (line 3) +* Precision: Nomenclature and Types. + (line 20) +* Precision <1>: MPFR Interface. (line 17) +* Reporting bugs: Reporting Bugs. (line 6) +* Rounding mode related functions: Rounding Related Functions. + (line 3) +* Rounding Modes: Nomenclature and Types. + (line 34) +* Special functions: Special Functions. (line 3) +* ‘stdarg.h’: Headers and Libraries. + (line 19) +* ‘stdint.h’: Headers and Libraries. + (line 22) +* ‘stdio.h’: Headers and Libraries. + (line 12) +* Ternary value: Rounding Modes. (line 24) +* ‘uintmax_t’: Headers and Libraries. + (line 22) + + +File: mpfr.info, Node: Function and Type Index, Prev: Concept Index, Up: Top + +Function and Type Index +*********************** + + +* Menu: + +* mpfr_abs: Basic Arithmetic Functions. + (line 160) +* mpfr_acos: Special Functions. (line 51) +* mpfr_acosh: Special Functions. (line 115) +* mpfr_add: Basic Arithmetic Functions. + (line 6) +* mpfr_add_d: Basic Arithmetic Functions. + (line 12) +* mpfr_add_q: Basic Arithmetic Functions. + (line 16) +* mpfr_add_si: Basic Arithmetic Functions. + (line 10) +* mpfr_add_ui: Basic Arithmetic Functions. + (line 8) +* mpfr_add_z: Basic Arithmetic Functions. + (line 14) +* mpfr_agm: Special Functions. (line 210) +* mpfr_ai: Special Functions. (line 226) +* mpfr_asin: Special Functions. (line 52) +* mpfr_asinh: Special Functions. (line 116) +* mpfr_asprintf: Formatted Output Functions. + (line 193) +* mpfr_atan: Special Functions. (line 53) +* mpfr_atan2: Special Functions. (line 63) +* mpfr_atanh: Special Functions. (line 117) +* mpfr_buildopt_decimal_p: Miscellaneous Functions. + (line 162) +* mpfr_buildopt_gmpinternals_p: Miscellaneous Functions. + (line 167) +* mpfr_buildopt_tls_p: Miscellaneous Functions. + (line 156) +* mpfr_buildopt_tune_case: Miscellaneous Functions. + (line 172) +* mpfr_can_round: Rounding Related Functions. + (line 39) +* mpfr_cbrt: Basic Arithmetic Functions. + (line 108) +* mpfr_ceil: Integer Related Functions. + (line 7) +* mpfr_check_range: Exception Related Functions. + (line 37) +* mpfr_clear: Initialization Functions. + (line 30) +* mpfr_clears: Initialization Functions. + (line 35) +* mpfr_clear_divby0: Exception Related Functions. + (line 112) +* mpfr_clear_erangeflag: Exception Related Functions. + (line 115) +* mpfr_clear_flags: Exception Related Functions. + (line 128) +* mpfr_clear_inexflag: Exception Related Functions. + (line 114) +* mpfr_clear_nanflag: Exception Related Functions. + (line 113) +* mpfr_clear_overflow: Exception Related Functions. + (line 111) +* mpfr_clear_underflow: Exception Related Functions. + (line 110) +* mpfr_cmp: Comparison Functions. + (line 6) +* mpfr_cmpabs: Comparison Functions. + (line 34) +* mpfr_cmp_d: Comparison Functions. + (line 9) +* mpfr_cmp_f: Comparison Functions. + (line 13) +* mpfr_cmp_ld: Comparison Functions. + (line 10) +* mpfr_cmp_q: Comparison Functions. + (line 12) +* mpfr_cmp_si: Comparison Functions. + (line 8) +* mpfr_cmp_si_2exp: Comparison Functions. + (line 29) +* mpfr_cmp_ui: Comparison Functions. + (line 7) +* mpfr_cmp_ui_2exp: Comparison Functions. + (line 27) +* mpfr_cmp_z: Comparison Functions. + (line 11) +* mpfr_const_catalan: Special Functions. (line 237) +* mpfr_const_euler: Special Functions. (line 236) +* mpfr_const_log2: Special Functions. (line 234) +* mpfr_const_pi: Special Functions. (line 235) +* mpfr_copysign: Miscellaneous Functions. + (line 109) +* mpfr_cos: Special Functions. (line 29) +* mpfr_cosh: Special Functions. (line 95) +* mpfr_cot: Special Functions. (line 47) +* mpfr_coth: Special Functions. (line 111) +* mpfr_csc: Special Functions. (line 46) +* mpfr_csch: Special Functions. (line 110) +* mpfr_custom_get_exp: Custom Interface. (line 75) +* mpfr_custom_get_kind: Custom Interface. (line 65) +* mpfr_custom_get_significand: Custom Interface. (line 70) +* mpfr_custom_get_size: Custom Interface. (line 37) +* mpfr_custom_init: Custom Interface. (line 41) +* mpfr_custom_init_set: Custom Interface. (line 48) +* mpfr_custom_move: Custom Interface. (line 82) +* MPFR_DECL_INIT: Initialization Functions. + (line 74) +* mpfr_digamma: Special Functions. (line 166) +* mpfr_dim: Basic Arithmetic Functions. + (line 166) +* mpfr_div: Basic Arithmetic Functions. + (line 72) +* mpfr_divby0_p: Exception Related Functions. + (line 134) +* mpfr_div_2exp: Compatibility with MPF. + (line 49) +* mpfr_div_2si: Basic Arithmetic Functions. + (line 181) +* mpfr_div_2ui: Basic Arithmetic Functions. + (line 179) +* mpfr_div_d: Basic Arithmetic Functions. + (line 84) +* mpfr_div_q: Basic Arithmetic Functions. + (line 88) +* mpfr_div_si: Basic Arithmetic Functions. + (line 80) +* mpfr_div_ui: Basic Arithmetic Functions. + (line 76) +* mpfr_div_z: Basic Arithmetic Functions. + (line 86) +* mpfr_d_div: Basic Arithmetic Functions. + (line 82) +* mpfr_d_sub: Basic Arithmetic Functions. + (line 35) +* mpfr_eint: Special Functions. (line 133) +* mpfr_eq: Compatibility with MPF. + (line 28) +* mpfr_equal_p: Comparison Functions. + (line 59) +* mpfr_erangeflag_p: Exception Related Functions. + (line 137) +* mpfr_erf: Special Functions. (line 177) +* mpfr_erfc: Special Functions. (line 178) +* mpfr_exp: Special Functions. (line 23) +* mpfr_exp10: Special Functions. (line 25) +* mpfr_exp2: Special Functions. (line 24) +* mpfr_expm1: Special Functions. (line 129) +* mpfr_fac_ui: Special Functions. (line 121) +* mpfr_fits_intmax_p: Conversion Functions. + (line 150) +* mpfr_fits_sint_p: Conversion Functions. + (line 146) +* mpfr_fits_slong_p: Conversion Functions. + (line 144) +* mpfr_fits_sshort_p: Conversion Functions. + (line 148) +* mpfr_fits_uintmax_p: Conversion Functions. + (line 149) +* mpfr_fits_uint_p: Conversion Functions. + (line 145) +* mpfr_fits_ulong_p: Conversion Functions. + (line 143) +* mpfr_fits_ushort_p: Conversion Functions. + (line 147) +* mpfr_floor: Integer Related Functions. + (line 8) +* mpfr_fma: Special Functions. (line 203) +* mpfr_fmod: Integer Related Functions. + (line 92) +* mpfr_fms: Special Functions. (line 205) +* mpfr_fprintf: Formatted Output Functions. + (line 157) +* mpfr_frac: Integer Related Functions. + (line 76) +* mpfr_free_cache: Special Functions. (line 244) +* mpfr_free_str: Conversion Functions. + (line 137) +* mpfr_frexp: Conversion Functions. + (line 45) +* mpfr_gamma: Special Functions. (line 148) +* mpfr_get_d: Conversion Functions. + (line 7) +* mpfr_get_decimal64: Conversion Functions. + (line 9) +* mpfr_get_default_prec: Initialization Functions. + (line 112) +* mpfr_get_default_rounding_mode: Rounding Related Functions. + (line 10) +* mpfr_get_d_2exp: Conversion Functions. + (line 32) +* mpfr_get_emax: Exception Related Functions. + (line 7) +* mpfr_get_emax_max: Exception Related Functions. + (line 30) +* mpfr_get_emax_min: Exception Related Functions. + (line 29) +* mpfr_get_emin: Exception Related Functions. + (line 6) +* mpfr_get_emin_max: Exception Related Functions. + (line 28) +* mpfr_get_emin_min: Exception Related Functions. + (line 27) +* mpfr_get_exp: Miscellaneous Functions. + (line 88) +* mpfr_get_f: Conversion Functions. + (line 72) +* mpfr_get_flt: Conversion Functions. + (line 6) +* mpfr_get_ld: Conversion Functions. + (line 8) +* mpfr_get_ld_2exp: Conversion Functions. + (line 34) +* mpfr_get_patches: Miscellaneous Functions. + (line 147) +* mpfr_get_prec: Initialization Functions. + (line 149) +* mpfr_get_si: Conversion Functions. + (line 19) +* mpfr_get_sj: Conversion Functions. + (line 21) +* mpfr_get_str: Conversion Functions. + (line 85) +* mpfr_get_ui: Conversion Functions. + (line 20) +* mpfr_get_uj: Conversion Functions. + (line 22) +* mpfr_get_version: Miscellaneous Functions. + (line 116) +* mpfr_get_z: Conversion Functions. + (line 67) +* mpfr_get_z_2exp: Conversion Functions. + (line 54) +* mpfr_grandom: Miscellaneous Functions. + (line 63) +* mpfr_greaterequal_p: Comparison Functions. + (line 56) +* mpfr_greater_p: Comparison Functions. + (line 55) +* mpfr_hypot: Special Functions. (line 218) +* mpfr_inexflag_p: Exception Related Functions. + (line 136) +* mpfr_inf_p: Comparison Functions. + (line 40) +* mpfr_init: Initialization Functions. + (line 53) +* mpfr_init2: Initialization Functions. + (line 10) +* mpfr_inits: Initialization Functions. + (line 62) +* mpfr_inits2: Initialization Functions. + (line 22) +* mpfr_init_set: Combined Initialization and Assignment Functions. + (line 6) +* mpfr_init_set_d: Combined Initialization and Assignment Functions. + (line 11) +* mpfr_init_set_f: Combined Initialization and Assignment Functions. + (line 16) +* mpfr_init_set_ld: Combined Initialization and Assignment Functions. + (line 12) +* mpfr_init_set_q: Combined Initialization and Assignment Functions. + (line 15) +* mpfr_init_set_si: Combined Initialization and Assignment Functions. + (line 9) +* mpfr_init_set_str: Combined Initialization and Assignment Functions. + (line 21) +* mpfr_init_set_ui: Combined Initialization and Assignment Functions. + (line 7) +* mpfr_init_set_z: Combined Initialization and Assignment Functions. + (line 14) +* mpfr_inp_str: Input and Output Functions. + (line 31) +* mpfr_integer_p: Integer Related Functions. + (line 119) +* mpfr_j0: Special Functions. (line 182) +* mpfr_j1: Special Functions. (line 183) +* mpfr_jn: Special Functions. (line 184) +* mpfr_lessequal_p: Comparison Functions. + (line 58) +* mpfr_lessgreater_p: Comparison Functions. + (line 64) +* mpfr_less_p: Comparison Functions. + (line 57) +* mpfr_lgamma: Special Functions. (line 157) +* mpfr_li2: Special Functions. (line 143) +* mpfr_lngamma: Special Functions. (line 152) +* mpfr_log: Special Functions. (line 16) +* mpfr_log10: Special Functions. (line 18) +* mpfr_log1p: Special Functions. (line 125) +* mpfr_log2: Special Functions. (line 17) +* mpfr_max: Miscellaneous Functions. + (line 22) +* mpfr_min: Miscellaneous Functions. + (line 20) +* mpfr_min_prec: Rounding Related Functions. + (line 64) +* mpfr_modf: Integer Related Functions. + (line 82) +* mpfr_mul: Basic Arithmetic Functions. + (line 51) +* mpfr_mul_2exp: Compatibility with MPF. + (line 47) +* mpfr_mul_2si: Basic Arithmetic Functions. + (line 174) +* mpfr_mul_2ui: Basic Arithmetic Functions. + (line 172) +* mpfr_mul_d: Basic Arithmetic Functions. + (line 57) +* mpfr_mul_q: Basic Arithmetic Functions. + (line 61) +* mpfr_mul_si: Basic Arithmetic Functions. + (line 55) +* mpfr_mul_ui: Basic Arithmetic Functions. + (line 53) +* mpfr_mul_z: Basic Arithmetic Functions. + (line 59) +* mpfr_nanflag_p: Exception Related Functions. + (line 135) +* mpfr_nan_p: Comparison Functions. + (line 39) +* mpfr_neg: Basic Arithmetic Functions. + (line 159) +* mpfr_nextabove: Miscellaneous Functions. + (line 15) +* mpfr_nextbelow: Miscellaneous Functions. + (line 16) +* mpfr_nexttoward: Miscellaneous Functions. + (line 6) +* mpfr_number_p: Comparison Functions. + (line 41) +* mpfr_out_str: Input and Output Functions. + (line 15) +* mpfr_overflow_p: Exception Related Functions. + (line 133) +* mpfr_pow: Basic Arithmetic Functions. + (line 116) +* mpfr_pow_si: Basic Arithmetic Functions. + (line 120) +* mpfr_pow_ui: Basic Arithmetic Functions. + (line 118) +* mpfr_pow_z: Basic Arithmetic Functions. + (line 122) +* mpfr_prec_round: Rounding Related Functions. + (line 13) +* ‘mpfr_prec_t’: Nomenclature and Types. + (line 20) +* mpfr_printf: Formatted Output Functions. + (line 164) +* mpfr_print_rnd_mode: Rounding Related Functions. + (line 71) +* mpfr_rec_sqrt: Basic Arithmetic Functions. + (line 103) +* mpfr_regular_p: Comparison Functions. + (line 43) +* mpfr_reldiff: Compatibility with MPF. + (line 39) +* mpfr_remainder: Integer Related Functions. + (line 94) +* mpfr_remquo: Integer Related Functions. + (line 96) +* mpfr_rint: Integer Related Functions. + (line 6) +* mpfr_rint_ceil: Integer Related Functions. + (line 46) +* mpfr_rint_floor: Integer Related Functions. + (line 47) +* mpfr_rint_round: Integer Related Functions. + (line 49) +* mpfr_rint_trunc: Integer Related Functions. + (line 51) +* ‘mpfr_rnd_t’: Nomenclature and Types. + (line 34) +* mpfr_root: Basic Arithmetic Functions. + (line 109) +* mpfr_round: Integer Related Functions. + (line 9) +* mpfr_sec: Special Functions. (line 45) +* mpfr_sech: Special Functions. (line 109) +* mpfr_set: Assignment Functions. + (line 9) +* mpfr_setsign: Miscellaneous Functions. + (line 103) +* mpfr_set_d: Assignment Functions. + (line 16) +* mpfr_set_decimal64: Assignment Functions. + (line 19) +* mpfr_set_default_prec: Initialization Functions. + (line 100) +* mpfr_set_default_rounding_mode: Rounding Related Functions. + (line 6) +* mpfr_set_divby0: Exception Related Functions. + (line 121) +* mpfr_set_emax: Exception Related Functions. + (line 16) +* mpfr_set_emin: Exception Related Functions. + (line 15) +* mpfr_set_erangeflag: Exception Related Functions. + (line 124) +* mpfr_set_exp: Miscellaneous Functions. + (line 93) +* mpfr_set_f: Assignment Functions. + (line 23) +* mpfr_set_flt: Assignment Functions. + (line 15) +* mpfr_set_inexflag: Exception Related Functions. + (line 123) +* mpfr_set_inf: Assignment Functions. + (line 143) +* mpfr_set_ld: Assignment Functions. + (line 17) +* mpfr_set_nan: Assignment Functions. + (line 142) +* mpfr_set_nanflag: Exception Related Functions. + (line 122) +* mpfr_set_overflow: Exception Related Functions. + (line 120) +* mpfr_set_prec: Initialization Functions. + (line 135) +* mpfr_set_prec_raw: Compatibility with MPF. + (line 22) +* mpfr_set_q: Assignment Functions. + (line 22) +* mpfr_set_si: Assignment Functions. + (line 12) +* mpfr_set_si_2exp: Assignment Functions. + (line 50) +* mpfr_set_sj: Assignment Functions. + (line 14) +* mpfr_set_sj_2exp: Assignment Functions. + (line 54) +* mpfr_set_str: Assignment Functions. + (line 62) +* mpfr_set_ui: Assignment Functions. + (line 10) +* mpfr_set_ui_2exp: Assignment Functions. + (line 48) +* mpfr_set_uj: Assignment Functions. + (line 13) +* mpfr_set_uj_2exp: Assignment Functions. + (line 52) +* mpfr_set_underflow: Exception Related Functions. + (line 119) +* mpfr_set_z: Assignment Functions. + (line 21) +* mpfr_set_zero: Assignment Functions. + (line 144) +* mpfr_set_z_2exp: Assignment Functions. + (line 56) +* mpfr_sgn: Comparison Functions. + (line 49) +* mpfr_signbit: Miscellaneous Functions. + (line 99) +* mpfr_sin: Special Functions. (line 30) +* mpfr_sinh: Special Functions. (line 96) +* mpfr_sinh_cosh: Special Functions. (line 101) +* mpfr_sin_cos: Special Functions. (line 35) +* mpfr_si_div: Basic Arithmetic Functions. + (line 78) +* mpfr_si_sub: Basic Arithmetic Functions. + (line 31) +* mpfr_snprintf: Formatted Output Functions. + (line 180) +* mpfr_sprintf: Formatted Output Functions. + (line 170) +* mpfr_sqr: Basic Arithmetic Functions. + (line 69) +* mpfr_sqrt: Basic Arithmetic Functions. + (line 96) +* mpfr_sqrt_ui: Basic Arithmetic Functions. + (line 97) +* mpfr_strtofr: Assignment Functions. + (line 80) +* mpfr_sub: Basic Arithmetic Functions. + (line 25) +* mpfr_subnormalize: Exception Related Functions. + (line 60) +* mpfr_sub_d: Basic Arithmetic Functions. + (line 37) +* mpfr_sub_q: Basic Arithmetic Functions. + (line 43) +* mpfr_sub_si: Basic Arithmetic Functions. + (line 33) +* mpfr_sub_ui: Basic Arithmetic Functions. + (line 29) +* mpfr_sub_z: Basic Arithmetic Functions. + (line 41) +* mpfr_sum: Special Functions. (line 252) +* mpfr_swap: Assignment Functions. + (line 150) +* ‘mpfr_t’: Nomenclature and Types. + (line 6) +* mpfr_tan: Special Functions. (line 31) +* mpfr_tanh: Special Functions. (line 97) +* mpfr_trunc: Integer Related Functions. + (line 10) +* mpfr_ui_div: Basic Arithmetic Functions. + (line 74) +* mpfr_ui_pow: Basic Arithmetic Functions. + (line 126) +* mpfr_ui_pow_ui: Basic Arithmetic Functions. + (line 124) +* mpfr_ui_sub: Basic Arithmetic Functions. + (line 27) +* mpfr_underflow_p: Exception Related Functions. + (line 132) +* mpfr_unordered_p: Comparison Functions. + (line 69) +* mpfr_urandom: Miscellaneous Functions. + (line 48) +* mpfr_urandomb: Miscellaneous Functions. + (line 29) +* mpfr_vasprintf: Formatted Output Functions. + (line 194) +* MPFR_VERSION: Miscellaneous Functions. + (line 119) +* MPFR_VERSION_MAJOR: Miscellaneous Functions. + (line 120) +* MPFR_VERSION_MINOR: Miscellaneous Functions. + (line 121) +* MPFR_VERSION_NUM: Miscellaneous Functions. + (line 139) +* MPFR_VERSION_PATCHLEVEL: Miscellaneous Functions. + (line 122) +* MPFR_VERSION_STRING: Miscellaneous Functions. + (line 123) +* mpfr_vfprintf: Formatted Output Functions. + (line 158) +* mpfr_vprintf: Formatted Output Functions. + (line 165) +* mpfr_vsnprintf: Formatted Output Functions. + (line 182) +* mpfr_vsprintf: Formatted Output Functions. + (line 171) +* mpfr_y0: Special Functions. (line 193) +* mpfr_y1: Special Functions. (line 194) +* mpfr_yn: Special Functions. (line 195) +* mpfr_zero_p: Comparison Functions. + (line 42) +* mpfr_zeta: Special Functions. (line 171) +* mpfr_zeta_ui: Special Functions. (line 172) +* mpfr_z_sub: Basic Arithmetic Functions. + (line 39) + + + +Tag Table: +Node: Top775 +Node: Copying2007 +Node: Introduction to MPFR3766 +Node: Installing MPFR5880 +Node: Reporting Bugs11323 +Node: MPFR Basics13353 +Node: Headers and Libraries13669 +Node: Nomenclature and Types16828 +Node: MPFR Variable Conventions18874 +Node: Rounding Modes20418 +Ref: ternary value21544 +Node: Floating-Point Values on Special Numbers23526 +Node: Exceptions26572 +Node: Memory Handling29749 +Node: MPFR Interface30894 +Node: Initialization Functions33008 +Node: Assignment Functions40318 +Node: Combined Initialization and Assignment Functions49673 +Node: Conversion Functions50974 +Node: Basic Arithmetic Functions60035 +Node: Comparison Functions69200 +Node: Special Functions72687 +Node: Input and Output Functions86672 +Node: Formatted Output Functions88644 +Node: Integer Related Functions98431 +Node: Rounding Related Functions105051 +Node: Miscellaneous Functions108888 +Node: Exception Related Functions117568 +Node: Compatibility with MPF124386 +Node: Custom Interface127127 +Node: Internals131526 +Node: API Compatibility133066 +Node: Type and Macro Changes134995 +Node: Added Functions137844 +Node: Changed Functions141132 +Node: Removed Functions145545 +Node: Other Changes145973 +Node: Contributors147576 +Node: References150219 +Node: GNU Free Documentation License151973 +Node: Concept Index174562 +Node: Function and Type Index180659 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: |