1This is mpfr.info, produced by makeinfo version 6.7 from mpfr.texi. 2 3This manual documents how to install and use the Multiple Precision 4Floating-Point Reliable Library, version 4.1.0. 5 6 Copyright 1991, 1993-2020 Free Software Foundation, Inc. 7 8 Permission is granted to copy, distribute and/or modify this document 9under the terms of the GNU Free Documentation License, Version 1.2 or 10any later version published by the Free Software Foundation; with no 11Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 12Texts. A copy of the license is included in *note GNU Free 13Documentation License::. 14INFO-DIR-SECTION Software libraries 15START-INFO-DIR-ENTRY 16* mpfr: (mpfr). Multiple Precision Floating-Point Reliable Library. 17END-INFO-DIR-ENTRY 18 19 20File: mpfr.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) 21 22GNU MPFR 23******** 24 25This manual documents how to install and use the Multiple Precision 26Floating-Point Reliable Library, version 4.1.0. 27 28 Copyright 1991, 1993-2020 Free Software Foundation, Inc. 29 30 Permission is granted to copy, distribute and/or modify this document 31under the terms of the GNU Free Documentation License, Version 1.2 or 32any later version published by the Free Software Foundation; with no 33Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 34Texts. A copy of the license is included in *note GNU Free 35Documentation License::. 36 37* Menu: 38 39* Copying:: MPFR Copying Conditions (LGPL). 40* Introduction to MPFR:: Brief introduction to GNU MPFR. 41* Installing MPFR:: How to configure and compile the MPFR library. 42* Reporting Bugs:: How to usefully report bugs. 43* MPFR Basics:: What every MPFR user should now. 44* MPFR Interface:: MPFR functions and macros. 45* API Compatibility:: API compatibility with previous MPFR versions. 46* MPFR and the IEEE 754 Standard:: 47* Contributors:: 48* References:: 49* GNU Free Documentation License:: 50* Concept Index:: 51* Function and Type Index:: 52 53 54File: mpfr.info, Node: Copying, Next: Introduction to MPFR, Prev: Top, Up: Top 55 56MPFR Copying Conditions 57*********************** 58 59The GNU MPFR library (or MPFR for short) is “free”; this means that 60everyone is free to use it and free to redistribute it on a free basis. 61The library is not in the public domain; it is copyrighted and there are 62restrictions on its distribution, but these restrictions are designed to 63permit everything that a good cooperating citizen would want to do. 64What is not allowed is to try to prevent others from further sharing any 65version of this library that they might get from you. 66 67 Specifically, we want to make sure that you have the right to give 68away copies of the library, that you receive source code or else can get 69it if you want it, that you can change this library or use pieces of it 70in new free programs, and that you know you can do these things. 71 72 To make sure that everyone has such rights, we have to forbid you to 73deprive anyone else of these rights. For example, if you distribute 74copies of the GNU MPFR library, you must give the recipients all the 75rights that you have. You must make sure that they, too, receive or can 76get the source code. And you must tell them their rights. 77 78 Also, for our own protection, we must make certain that everyone 79finds out that there is no warranty for the GNU MPFR library. If it is 80modified by someone else and passed on, we want their recipients to know 81that what they have is not what we distributed, so that any problems 82introduced by others will not reflect on our reputation. 83 84 The precise conditions of the license for the GNU MPFR library are 85found in the Lesser General Public License that accompanies the source 86code. See the file COPYING.LESSER. 87 88 89File: mpfr.info, Node: Introduction to MPFR, Next: Installing MPFR, Prev: Copying, Up: Top 90 911 Introduction to MPFR 92********************** 93 94MPFR is a portable library written in C for arbitrary precision 95arithmetic on floating-point numbers. It is based on the GNU MP 96library. It aims to provide a class of floating-point numbers with 97precise semantics. The main characteristics of MPFR, which make it 98differ from most arbitrary precision floating-point software tools, are: 99 100 • the MPFR code is portable, i.e., the result of any operation does 101 not depend on the machine word size ‘mp_bits_per_limb’ (64 on most 102 current processors), possibly except in faithful rounding. It does 103 not depend either on the machine rounding mode or rounding 104 precision; 105 106 • the precision in bits can be set _exactly_ to any valid value for 107 each variable (including very small precision); 108 109 • MPFR provides the four rounding modes from the IEEE 754-1985 110 standard, plus away-from-zero, as well as for basic operations as 111 for other mathematical functions. Faithful rounding (partially 112 supported) is provided too, but the results may no longer be 113 reproducible. 114 115 In particular, with a precision of 53 bits and in any of the four 116standard rounding modes, MPFR is able to exactly reproduce all 117computations with double-precision machine floating-point numbers (e.g., 118‘double’ type in C, with a C implementation that rigorously follows 119Annex F of the ISO C99 standard and ‘FP_CONTRACT’ pragma set to ‘OFF’) 120on the four arithmetic operations and the square root, except the 121default exponent range is much wider and subnormal numbers are not 122implemented (but can be emulated). 123 124 This version of MPFR is released under the GNU Lesser General Public 125License, version 3 or any later version. It is permitted to link MPFR 126to most non-free programs, as long as when distributing them the MPFR 127source code and a means to re-link with a modified MPFR library is 128provided. 129 1301.1 How to Use This Manual 131========================== 132 133Everyone should read *note MPFR Basics::. If you need to install the 134library yourself, you need to read *note Installing MPFR::, too. To use 135the library you will need to refer to *note MPFR Interface::. 136 137 The rest of the manual can be used for later reference, although it 138is probably a good idea to glance through it. 139 140 141File: mpfr.info, Node: Installing MPFR, Next: Reporting Bugs, Prev: Introduction to MPFR, Up: Top 142 1432 Installing MPFR 144***************** 145 146The MPFR library is already installed on some GNU/Linux distributions, 147but the development files necessary to the compilation such as ‘mpfr.h’ 148are not always present. To check that MPFR is fully installed on your 149computer, you can check the presence of the file ‘mpfr.h’ in 150‘/usr/include’, or try to compile a small program having ‘#include 151<mpfr.h>’ (since ‘mpfr.h’ may be installed somewhere else). For 152instance, you can try to compile: 153 154 #include <stdio.h> 155 #include <mpfr.h> 156 int main (void) 157 { 158 printf ("MPFR library: %-12s\nMPFR header: %s (based on %d.%d.%d)\n", 159 mpfr_get_version (), MPFR_VERSION_STRING, MPFR_VERSION_MAJOR, 160 MPFR_VERSION_MINOR, MPFR_VERSION_PATCHLEVEL); 161 return 0; 162 } 163 164with 165 166 cc -o version version.c -lmpfr -lgmp 167 168and if you get errors whose first line looks like 169 170 version.c:2:19: error: mpfr.h: No such file or directory 171 172then MPFR is probably not installed. Running this program will give you 173the MPFR version. 174 175 If MPFR is not installed on your computer, or if you want to install 176a different version, please follow the steps below. 177 1782.1 How to Install 179================== 180 181Here are the steps needed to install the library on Unix systems (more 182details are provided in the ‘INSTALL’ file): 183 184 1. To build MPFR, you first have to install GNU MP (version 5.0.0 or 185 higher) on your computer. You need a C compiler, preferably GCC, 186 but any reasonable compiler should work. And you need the standard 187 Unix ‘make’ command, plus some other standard Unix utility 188 commands. 189 190 Then, in the MPFR build directory, type the following commands. 191 192 2. ‘./configure’ 193 194 This will prepare the build and setup the options according to your 195 system. You can give options to specify the install directories 196 (instead of the default ‘/usr/local’), threading support, and so 197 on. See the ‘INSTALL’ file and/or the output of ‘./configure 198 --help’ for more information, in particular if you get error 199 messages. 200 201 3. ‘make’ 202 203 This will compile MPFR, and create a library archive file 204 ‘libmpfr.a’. On most platforms, a dynamic library will be produced 205 too. 206 207 4. ‘make check’ 208 209 This will make sure that MPFR was built correctly. If any test 210 fails, information about this failure can be found in the 211 ‘tests/test-suite.log’ file. If you want the contents of this file 212 to be automatically output in case of failure, you can set the 213 ‘VERBOSE’ environment variable to 1 before running ‘make check’, 214 for instance by typing: 215 216 ‘VERBOSE=1 make check’ 217 218 In case of failure, you may want to check whether the problem is 219 already known. If not, please report this failure to the MPFR 220 mailing-list ‘mpfr@inria.fr’. For details, see *note Reporting 221 Bugs::. 222 223 5. ‘make install’ 224 225 This will copy the files ‘mpfr.h’ and ‘mpf2mpfr.h’ to the directory 226 ‘/usr/local/include’, the library files (‘libmpfr.a’ and possibly 227 others) to the directory ‘/usr/local/lib’, the file ‘mpfr.info’ to 228 the directory ‘/usr/local/share/info’, and some other documentation 229 files to the directory ‘/usr/local/share/doc/mpfr’ (or if you 230 passed the ‘--prefix’ option to ‘configure’, using the prefix 231 directory given as argument to ‘--prefix’ instead of ‘/usr/local’). 232 2332.2 Other ‘make’ Targets 234======================== 235 236There are some other useful make targets: 237 238 • ‘mpfr.info’ or ‘info’ 239 240 Create or update an info version of the manual, in ‘mpfr.info’. 241 242 This file is already provided in the MPFR archives. 243 244 • ‘mpfr.pdf’ or ‘pdf’ 245 246 Create a PDF version of the manual, in ‘mpfr.pdf’. 247 248 • ‘mpfr.dvi’ or ‘dvi’ 249 250 Create a DVI version of the manual, in ‘mpfr.dvi’. 251 252 • ‘mpfr.ps’ or ‘ps’ 253 254 Create a Postscript version of the manual, in ‘mpfr.ps’. 255 256 • ‘mpfr.html’ or ‘html’ 257 258 Create a HTML version of the manual, in several pages in the 259 directory ‘doc/mpfr.html’; if you want only one output HTML file, 260 then type ‘makeinfo --html --no-split mpfr.texi’ from the ‘doc’ 261 directory instead. 262 263 • ‘clean’ 264 265 Delete all object files and archive files, but not the 266 configuration files. 267 268 • ‘distclean’ 269 270 Delete all generated files not included in the distribution. 271 272 • ‘uninstall’ 273 274 Delete all files copied by ‘make install’. 275 2762.3 Build Problems 277================== 278 279In case of problem, please read the ‘INSTALL’ file carefully before 280reporting a bug, in particular section “In case of problem”. Some 281problems are due to bad configuration on the user side (not specific to 282MPFR). Problems are also mentioned in the FAQ 283<https://www.mpfr.org/faq.html>. 284 285 Please report problems to the MPFR mailing-list ‘mpfr@inria.fr’. 286*Note Reporting Bugs::. Some bug fixes are available on the MPFR 4.1.0 287web page <https://www.mpfr.org/mpfr-4.1.0/>. 288 2892.4 Getting the Latest Version of MPFR 290====================================== 291 292The latest version of MPFR is available from 293<https://ftp.gnu.org/gnu/mpfr/> or <https://www.mpfr.org/>. 294 295 296File: mpfr.info, Node: Reporting Bugs, Next: MPFR Basics, Prev: Installing MPFR, Up: Top 297 2983 Reporting Bugs 299**************** 300 301If you think you have found a bug in the MPFR library, first have a look 302on the MPFR 4.1.0 web page <https://www.mpfr.org/mpfr-4.1.0/> and the 303FAQ <https://www.mpfr.org/faq.html>: perhaps this bug is already known, 304in which case you may find there a workaround for it. You might also 305look in the archives of the MPFR mailing-list: 306<https://sympa.inria.fr/sympa/arc/mpfr>. Otherwise, please investigate 307and report it. We have made this library available to you, and it is 308not to ask too much from you, to ask you to report the bugs that you 309find. 310 311 There are a few things you should think about when you put your bug 312report together. 313 314 You have to send us a test case that makes it possible for us to 315reproduce the bug, i.e., a small self-content program, using no other 316library than MPFR. Include instructions on how to run the test case. 317 318 You also have to explain what is wrong; if you get a crash, or if the 319results you get are incorrect and in that case, in what way. 320 321 Please include compiler version information in your bug report. This 322can be extracted using ‘cc -V’ on some machines, or, if you are using 323GCC, ‘gcc -v’. Also, include the output from ‘uname -a’ and the MPFR 324version (the GMP version may be useful too). If you get a failure while 325running ‘make’ or ‘make check’, please include the ‘config.log’ file in 326your bug report, and in case of test failure, the ‘tests/test-suite.log’ 327file too. 328 329 If your bug report is good, we will do our best to help you to get a 330corrected version of the library; if the bug report is poor, we will not 331do anything about it (aside of chiding you to send better bug reports). 332 333 Send your bug report to the MPFR mailing-list ‘mpfr@inria.fr’. 334 335 If you think something in this manual is unclear, or downright 336incorrect, or if the language needs to be improved, please send a note 337to the same address. 338 339 340File: mpfr.info, Node: MPFR Basics, Next: MPFR Interface, Prev: Reporting Bugs, Up: Top 341 3424 MPFR Basics 343************* 344 345* Menu: 346 347* Headers and Libraries:: 348* Nomenclature and Types:: 349* MPFR Variable Conventions:: 350* Rounding:: 351* Floating-Point Values on Special Numbers:: 352* Exceptions:: 353* Memory Handling:: 354* Getting the Best Efficiency Out of MPFR:: 355 356 357File: mpfr.info, Node: Headers and Libraries, Next: Nomenclature and Types, Prev: MPFR Basics, Up: MPFR Basics 358 3594.1 Headers and Libraries 360========================= 361 362All declarations needed to use MPFR are collected in the include file 363‘mpfr.h’. It is designed to work with both C and C++ compilers. You 364should include that file in any program using the MPFR library: 365 366 #include <mpfr.h> 367 368 Note however that prototypes for MPFR functions with ‘FILE *’ 369parameters are provided only if ‘<stdio.h>’ is included too (before 370‘mpfr.h’): 371 372 #include <stdio.h> 373 #include <mpfr.h> 374 375 Likewise ‘<stdarg.h>’ (or ‘<varargs.h>’) is required for prototypes 376with ‘va_list’ parameters, such as ‘mpfr_vprintf’. 377 378 And for any functions using ‘intmax_t’, you must include ‘<stdint.h>’ 379or ‘<inttypes.h>’ before ‘mpfr.h’, to allow ‘mpfr.h’ to define 380prototypes for these functions. Moreover, under some platforms (in 381particular with C++ compilers), users may need to define 382‘MPFR_USE_INTMAX_T’ (and should do it for portability) before ‘mpfr.h’ 383has been included; of course, it is possible to do that on the command 384line, e.g., with ‘-DMPFR_USE_INTMAX_T’. 385 386 Note: If ‘mpfr.h’ and/or ‘gmp.h’ (used by ‘mpfr.h’) are included 387several times (possibly from another header file), ‘<stdio.h>’ and/or 388‘<stdarg.h>’ (or ‘<varargs.h>’) should be included *before the first 389inclusion* of ‘mpfr.h’ or ‘gmp.h’. Alternatively, you can define 390‘MPFR_USE_FILE’ (for MPFR I/O functions) and/or ‘MPFR_USE_VA_LIST’ (for 391MPFR functions with ‘va_list’ parameters) anywhere before the last 392inclusion of ‘mpfr.h’. As a consequence, if your file is a public 393header that includes ‘mpfr.h’, you need to use the latter method. 394 395 When calling a MPFR macro, it is not allowed to have previously 396defined a macro with the same name as some keywords (currently ‘do’, 397‘while’ and ‘sizeof’). 398 399 You can avoid the use of MPFR macros encapsulating functions by 400defining the ‘MPFR_USE_NO_MACRO’ macro before ‘mpfr.h’ is included. In 401general this should not be necessary, but this can be useful when 402debugging user code: with some macros, the compiler may emit spurious 403warnings with some warning options, and macros can prevent some 404prototype checking. 405 406 All programs using MPFR must link against both ‘libmpfr’ and ‘libgmp’ 407libraries. On a typical Unix-like system this can be done with ‘-lmpfr 408-lgmp’ (in that order), for example: 409 410 gcc myprogram.c -lmpfr -lgmp 411 412 MPFR is built using Libtool and an application can use that to link 413if desired, *note GNU Libtool: (libtool)Top. 414 415 If MPFR has been installed to a non-standard location, then it may be 416necessary to set up environment variables such as ‘C_INCLUDE_PATH’ and 417‘LIBRARY_PATH’, or use ‘-I’ and ‘-L’ compiler options, in order to point 418to the right directories. For a shared library, it may also be 419necessary to set up some sort of run-time library path (e.g., 420‘LD_LIBRARY_PATH’) on some systems. Please read the ‘INSTALL’ file for 421additional information. 422 423 Alternatively, it is possible to use ‘pkg-config’ (a file ‘mpfr.pc’ 424is provided as of MPFR 4.0): 425 426 cc myprogram.c $(pkg-config --cflags --libs mpfr) 427 428 Note that the ‘MPFR_’ and ‘mpfr_’ prefixes are reserved for MPFR. As 429a general rule, in order to avoid clashes, software using MPFR (directly 430or indirectly) and system headers/libraries should not define macros and 431symbols using these prefixes. 432 433 434File: mpfr.info, Node: Nomenclature and Types, Next: MPFR Variable Conventions, Prev: Headers and Libraries, Up: MPFR Basics 435 4364.2 Nomenclature and Types 437========================== 438 439A “floating-point number”, or “float” for short, is an object 440representing a radix-2 floating-point number consisting of a sign, an 441arbitrary-precision normalized significand (also called mantissa), and 442an exponent (an integer in some given range); these are called “regular 443numbers”. Like in the IEEE 754 standard, a floating-point number can 444also have three kinds of special values: a signed zero, a signed 445infinity, and Not-a-Number (NaN). NaN can represent the default value 446of a floating-point object and the result of some operations for which 447no other results would make sense, such as 0 divided by 0 or +Infinity 448minus +Infinity; unless documented otherwise, the sign bit of a NaN is 449unspecified. Note that contrary to IEEE 754, MPFR has a single kind of 450NaN and does not have subnormals. Other than that, the behavior is very 451similar to IEEE 754, but there may be some differences. 452 453 The C data type for such objects is ‘mpfr_t’, internally defined as a 454one-element array of a structure (so that when passed as an argument to 455a function, it is the pointer that is actually passed), and ‘mpfr_ptr’ 456is the C data type representing a pointer to this structure. 457 458 The “precision” is the number of bits used to represent the 459significand of a floating-point number; the corresponding C data type is 460‘mpfr_prec_t’. The precision can be any integer between ‘MPFR_PREC_MIN’ 461and ‘MPFR_PREC_MAX’. In the current implementation, ‘MPFR_PREC_MIN’ is 462equal to 1. 463 464 Warning! MPFR needs to increase the precision internally, in order 465to provide accurate results (and in particular, correct rounding). Do 466not attempt to set the precision to any value near ‘MPFR_PREC_MAX’, 467otherwise MPFR will abort due to an assertion failure. However, in 468practice, the real limitation will probably be the available memory on 469your platform, and in case of lack of memory, the program may abort, 470crash or have undefined behavior (depending on your C implementation). 471 472 An “exponent” is a component of a regular floating-point number. Its 473C data type is ‘mpfr_exp_t’. Valid exponents are restricted to a subset 474of this type, and the exponent range can be changed globally as 475described in *note Exception Related Functions::. Special values do not 476have an exponent. 477 478 The “rounding mode” specifies the way to round the result of a 479floating-point operation, in case the exact result cannot be represented 480exactly in the destination (*note Rounding::). The corresponding C data 481type is ‘mpfr_rnd_t’. 482 483 MPFR has a global (or per-thread) flag for each supported exception 484and provides operations on flags (*note Exceptions::). This C data type 485is used to represent a group of flags (or a mask). 486 487 488File: mpfr.info, Node: MPFR Variable Conventions, Next: Rounding, Prev: Nomenclature and Types, Up: MPFR Basics 489 4904.3 MPFR Variable Conventions 491============================= 492 493Before you can assign to a MPFR variable, you need to initialize it by 494calling one of the special initialization functions. When you are done 495with a variable, you need to clear it out, using one of the functions 496for that purpose. A variable should only be initialized once, or at 497least cleared out between each initialization. After a variable has 498been initialized, it may be assigned to any number of times. For 499efficiency reasons, avoid to initialize and clear out a variable in 500loops. Instead, initialize it before entering the loop, and clear it 501out after the loop has exited. You do not need to be concerned about 502allocating additional space for MPFR variables, since any variable has a 503significand of fixed size. Hence unless you change its precision, or 504clear and reinitialize it, a floating-point variable will have the same 505allocated space during all its life. 506 507 As a general rule, all MPFR functions expect output arguments before 508input arguments. This notation is based on an analogy with the 509assignment operator. MPFR allows you to use the same variable for both 510input and output in the same expression. For example, the main function 511for floating-point multiplication, ‘mpfr_mul’, can be used like this: 512‘mpfr_mul (x, x, x, rnd)’. This computes the square of X with rounding 513mode ‘rnd’ and puts the result back in X. 514 515 516File: mpfr.info, Node: Rounding, Next: Floating-Point Values on Special Numbers, Prev: MPFR Variable Conventions, Up: MPFR Basics 517 5184.4 Rounding 519============ 520 521The following rounding modes are supported: 522 523 • ‘MPFR_RNDN’: round to nearest, with the even rounding rule 524 (roundTiesToEven in IEEE 754-2008); see details below. 525 526 • ‘MPFR_RNDD’: round toward minus infinity (roundTowardNegative in 527 IEEE 754-2008). 528 529 • ‘MPFR_RNDU’: round toward plus infinity (roundTowardPositive in 530 IEEE 754-2008). 531 532 • ‘MPFR_RNDZ’: round toward zero (roundTowardZero in IEEE 754-2008). 533 534 • ‘MPFR_RNDA’: round away from zero. 535 536 • ‘MPFR_RNDF’: faithful rounding. This feature is currently 537 experimental. Specific support for this rounding mode has been 538 added to some functions, such as the basic operations (addition, 539 subtraction, multiplication, square, division, square root) or when 540 explicitly documented. It might also work with other functions, as 541 it is possible that they do not need modification in their code; 542 even though a correct behavior is not guaranteed yet (corrections 543 were done when failures occurred in the test suite, but almost 544 nothing has been checked manually), failures should be regarded as 545 bugs and reported, so that they can be fixed. 546 547 Note that, in particular for a result equal to zero, the sign is 548preserved by the rounding operation. 549 550 The ‘MPFR_RNDN’ mode works like roundTiesToEven from the IEEE 754 551standard: in case the number to be rounded lies exactly in the middle 552between two consecutive representable numbers, it is rounded to the one 553with an even significand; in radix 2, this means that the least 554significant bit is 0. For example, the number 2.5, which is represented 555by (10.1) in binary, is rounded to (10.0)=2 with a precision of two 556bits, and not to (11.0)=3. This rule avoids the “drift” phenomenon 557mentioned by Knuth in volume 2 of The Art of Computer Programming 558(Section 4.2.2). 559 560 Note: In particular for a 1-digit precision (in radix 2 or other 561radices, as in conversions to a string of digits), one considers the 562significands associated with the exponent of the number to be rounded. 563For instance, to round the number 95 in radix 10 with a 1-digit 564precision, one considers its truncated 1-digit integer significand 9 and 565the following integer 10 (since these are consecutive integers, exactly 566one of them is even). 10 is the even significand, so that 95 will be 567rounded to 100, not to 90. 568 569 For the “directed rounding modes”, a number X is rounded to the 570number Y that is the closest to X such that 571 • ‘MPFR_RNDD’: Y is less than or equal to X; 572 • ‘MPFR_RNDU’: Y is greater than or equal to X; 573 • ‘MPFR_RNDZ’: abs(Y) is less than or equal to abs(X); 574 • ‘MPFR_RNDA’: abs(Y) is greater than or equal to abs(X). 575 576 The ‘MPFR_RNDF’ mode works as follows: the computed value is either 577that corresponding to ‘MPFR_RNDD’ or that corresponding to ‘MPFR_RNDU’. 578In particular when those values are identical, i.e., when the result of 579the corresponding operation is exactly representable, that exact result 580is returned. Thus, the computed result can take at most two possible 581values, and in absence of underflow/overflow, the corresponding error is 582strictly less than one ulp (unit in the last place) of that result and 583of the exact result. For ‘MPFR_RNDF’, the ternary value (defined below) 584and the inexact flag (defined later, as with the other flags) are 585unspecified, the divide-by-zero flag is as with other roundings, and the 586underflow and overflow flags match what would be obtained in the case 587the computed value is the same as with ‘MPFR_RNDD’ or ‘MPFR_RNDU’. The 588results may not be reproducible. 589 590 Most MPFR functions take as first argument the destination variable, 591as second and following arguments the input variables, as last argument 592a rounding mode, and have a return value of type ‘int’, called the 593“ternary value”. The value stored in the destination variable is 594correctly rounded, i.e., MPFR behaves as if it computed the result with 595an infinite precision, then rounded it to the precision of this 596variable. The input variables are regarded as exact (in particular, 597their precision does not affect the result). 598 599 As a consequence, in case of a non-zero real rounded result, the 600error on the result is less than or equal to 1/2 ulp (unit in the last 601place) of that result in the rounding to nearest mode, and less than 1 602ulp of that result in the directed rounding modes (a ulp is the weight 603of the least significant represented bit of the result after rounding). 604 605 Unless documented otherwise, functions returning an ‘int’ return a 606ternary value. If the ternary value is zero, it means that the value 607stored in the destination variable is the exact result of the 608corresponding mathematical function. If the ternary value is positive 609(resp. negative), it means the value stored in the destination variable 610is greater (resp. lower) than the exact result. For example with the 611‘MPFR_RNDU’ rounding mode, the ternary value is usually positive, except 612when the result is exact, in which case it is zero. In the case of an 613infinite result, it is considered as inexact when it was obtained by 614overflow, and exact otherwise. A NaN result (Not-a-Number) always 615corresponds to an exact return value. The opposite of a returned 616ternary value is guaranteed to be representable in an ‘int’. 617 618 Unless documented otherwise, functions returning as result the value 619‘1’ (or any other value specified in this manual) for special cases 620(like ‘acos(0)’) yield an overflow or an underflow if that value is not 621representable in the current exponent range. 622 623 624File: mpfr.info, Node: Floating-Point Values on Special Numbers, Next: Exceptions, Prev: Rounding, Up: MPFR Basics 625 6264.5 Floating-Point Values on Special Numbers 627============================================ 628 629This section specifies the floating-point values (of type ‘mpfr_t’) 630returned by MPFR functions (where by “returned” we mean here the 631modified value of the destination object, which should not be mixed with 632the ternary return value of type ‘int’ of those functions). For 633functions returning several values (like ‘mpfr_sin_cos’), the rules 634apply to each result separately. 635 636 Functions can have one or several input arguments. An input point is 637a mapping from these input arguments to the set of the MPFR numbers. 638When none of its components are NaN, an input point can also be seen as 639a tuple in the extended real numbers (the set of the real numbers with 640both infinities). 641 642 When the input point is in the domain of the mathematical function, 643the result is rounded as described in *note Rounding:: (but see below 644for the specification of the sign of an exact zero). Otherwise the 645general rules from this section apply unless stated otherwise in the 646description of the MPFR function (*note MPFR Interface::). 647 648 When the input point is not in the domain of the mathematical 649function but is in its closure in the extended real numbers and the 650function can be extended by continuity, the result is the obtained 651limit. Examples: ‘mpfr_hypot’ on (+Inf,0) gives +Inf. But ‘mpfr_pow’ 652cannot be defined on (1,+Inf) using this rule, as one can find sequences 653(X_N,Y_N) such that X_N goes to 1, Y_N goes to +Inf and X_N to the Y_N 654goes to any positive value when N goes to the infinity. 655 656 When the input point is in the closure of the domain of the 657mathematical function and an input argument is +0 (resp. −0), one 658considers the limit when the corresponding argument approaches 0 from 659above (resp. below), if possible. If the limit is not defined (e.g., 660‘mpfr_sqrt’ and ‘mpfr_log’ on −0), the behavior is specified in the 661description of the MPFR function, but must be consistent with the rule 662from the above paragraph (e.g., ‘mpfr_log’ on ±0 gives −Inf). 663 664 When the result is equal to 0, its sign is determined by considering 665the limit as if the input point were not in the domain: If one 666approaches 0 from above (resp. below), the result is +0 (resp. −0); for 667example, ‘mpfr_sin’ on −0 gives −0 and ‘mpfr_acos’ on 1 gives +0 (in all 668rounding modes). In the other cases, the sign is specified in the 669description of the MPFR function; for example ‘mpfr_max’ on −0 and +0 670gives +0. 671 672 When the input point is not in the closure of the domain of the 673function, the result is NaN. Example: ‘mpfr_sqrt’ on −17 gives NaN. 674 675 When an input argument is NaN, the result is NaN, possibly except 676when a partial function is constant on the finite floating-point 677numbers; such a case is always explicitly specified in *note MPFR 678Interface::. Example: ‘mpfr_hypot’ on (NaN,0) gives NaN, but 679‘mpfr_hypot’ on (NaN,+Inf) gives +Inf (as specified in *note 680Transcendental Functions::), since for any finite or infinite input X, 681‘mpfr_hypot’ on (X,+Inf) gives +Inf. 682 683 684File: mpfr.info, Node: Exceptions, Next: Memory Handling, Prev: Floating-Point Values on Special Numbers, Up: MPFR Basics 685 6864.6 Exceptions 687============== 688 689MPFR defines a global (or per-thread) flag for each supported exception. 690A macro evaluating to a power of two is associated with each flag and 691exception, in order to be able to specify a group of flags (or a mask) 692by OR’ing such macros. 693 694 Flags can be cleared (lowered), set (raised), and tested by functions 695described in *note Exception Related Functions::. 696 697 The supported exceptions are listed below. The macro associated with 698each exception is in parentheses. 699 700 • Underflow (‘MPFR_FLAGS_UNDERFLOW’): An underflow occurs when the 701 exact result of a function is a non-zero real number and the result 702 obtained after the rounding, assuming an unbounded exponent range 703 (for the rounding), has an exponent smaller than the minimum value 704 of the current exponent range. (In the round-to-nearest mode, the 705 halfway case is rounded toward zero.) 706 707 Note: This is not the single possible definition of the underflow. 708 MPFR chooses to consider the underflow _after_ rounding. The 709 underflow before rounding can also be defined. For instance, 710 consider a function that has the exact result 7 multiplied by two 711 to the power E−4, where E is the smallest exponent (for a 712 significand between 1/2 and 1), with a 2-bit target precision and 713 rounding toward plus infinity. The exact result has the exponent 714 E−1. With the underflow before rounding, such a function call 715 would yield an underflow, as E−1 is outside the current exponent 716 range. However, MPFR first considers the rounded result assuming 717 an unbounded exponent range. The exact result cannot be 718 represented exactly in precision 2, and here, it is rounded to 0.5 719 times 2 to E, which is representable in the current exponent range. 720 As a consequence, this will not yield an underflow in MPFR. 721 722 • Overflow (‘MPFR_FLAGS_OVERFLOW’): An overflow occurs when the exact 723 result of a function is a non-zero real number and the result 724 obtained after the rounding, assuming an unbounded exponent range 725 (for the rounding), has an exponent larger than the maximum value 726 of the current exponent range. In the round-to-nearest mode, the 727 result is infinite. Note: unlike the underflow case, there is only 728 one possible definition of overflow here. 729 730 • Divide-by-zero (‘MPFR_FLAGS_DIVBY0’): An exact infinite result is 731 obtained from finite inputs. 732 733 • NaN (‘MPFR_FLAGS_NAN’): A NaN exception occurs when the result of a 734 function is NaN. 735 736 • Inexact (‘MPFR_FLAGS_INEXACT’): An inexact exception occurs when 737 the result of a function cannot be represented exactly and must be 738 rounded. 739 740 • Range error (‘MPFR_FLAGS_ERANGE’): A range exception occurs when a 741 function that does not return a MPFR number (such as comparisons 742 and conversions to an integer) has an invalid result (e.g., an 743 argument is NaN in ‘mpfr_cmp’, or a conversion to an integer cannot 744 be represented in the target type). 745 746 Moreover, the group consisting of all the flags is represented by the 747‘MPFR_FLAGS_ALL’ macro (if new flags are added in future MPFR versions, 748they will be added to this macro too). 749 750 Differences with the ISO C99 standard: 751 752 • In C, only quiet NaNs are specified, and a NaN propagation does not 753 raise an invalid exception. Unless explicitly stated otherwise, 754 MPFR sets the NaN flag whenever a NaN is generated, even when a NaN 755 is propagated (e.g., in NaN + NaN), as if all NaNs were signaling. 756 757 • An invalid exception in C corresponds to either a NaN exception or 758 a range error in MPFR. 759 760 761File: mpfr.info, Node: Memory Handling, Next: Getting the Best Efficiency Out of MPFR, Prev: Exceptions, Up: MPFR Basics 762 7634.7 Memory Handling 764=================== 765 766MPFR functions may create caches, e.g., when computing constants such as 767Pi, either because the user has called a function like ‘mpfr_const_pi’ 768directly or because such a function was called internally by the MPFR 769library itself to compute some other function. When more precision is 770needed, the value is automatically recomputed; a minimum of 10% increase 771of the precision is guaranteed to avoid too many recomputations. 772 773 MPFR functions may also create thread-local pools for internal use to 774avoid the cost of memory allocation. The pools can be freed with 775‘mpfr_free_pool’ (but with a default MPFR build, they should not take 776much memory, as the allocation size is limited). 777 778 At any time, the user can free various caches and pools with 779‘mpfr_free_cache’ and ‘mpfr_free_cache2’. It is strongly advised to 780free thread-local caches before terminating a thread, and all caches 781before exiting when using tools like ‘valgrind’ (to avoid memory leaks 782being reported). 783 784 MPFR allocates its memory either on the stack (for temporary memory 785only) or with the same allocator as the one configured for GMP: *note 786(gmp.info)Custom Allocation::. This means that the application must 787make sure that data allocated with the current allocator will not be 788reallocated or freed with a new allocator. So, in practice, if an 789application needs to change the allocator with 790‘mp_set_memory_functions’, it should first free all data allocated with 791the current allocator: for its own data, with ‘mpfr_clear’, etc.; for 792the caches and pools, with ‘mpfr_mp_memory_cleanup’ in all threads where 793MPFR is potentially used. This function is currently equivalent to 794‘mpfr_free_cache’, but ‘mpfr_mp_memory_cleanup’ is the recommended way 795in case the allocation method changes in the future (for instance, one 796may choose to allocate the caches for floating-point constants with 797‘malloc’ to avoid freeing them if the allocator changes). Developers 798should also be aware that MPFR may also be used indirectly by libraries, 799so that libraries based on MPFR should provide a clean-up function 800calling ‘mpfr_mp_memory_cleanup’ and/or warn their users about this 801issue. 802 803 Note: For multithreaded applications, the allocator must be valid in 804all threads where MPFR may be used; data allocated in one thread may be 805reallocated and/or freed in some other thread. 806 807 MPFR internal data such as flags, the exponent range, the default 808precision, and the default rounding mode are either global (if MPFR has 809not been compiled as thread safe) or per-thread (thread-local storage, 810TLS). The initial values of TLS data after a thread is created entirely 811depend on the compiler and thread implementation (MPFR simply does a 812conventional variable initialization, the variables being declared with 813an implementation-defined TLS specifier). 814 815 Writers of libraries using MPFR should be aware that the application 816and/or another library used by the application may also use MPFR, so 817that changing the exponent range, the default precision, or the default 818rounding mode may have an effect on this other use of MPFR since these 819data are not duplicated (unless they are in a different thread). 820Therefore any such value changed in a library function should be 821restored before the function returns (unless the purpose of the function 822is to do such a change). Writers of software using MPFR should also be 823careful when changing such a value if they use a library using MPFR 824(directly or indirectly), in order to make sure that such a change is 825compatible with the library. 826 827 828File: mpfr.info, Node: Getting the Best Efficiency Out of MPFR, Prev: Memory Handling, Up: MPFR Basics 829 8304.8 Getting the Best Efficiency Out of MPFR 831=========================================== 832 833Here are a few hints to get the best efficiency out of MPFR: 834 835 • you should avoid allocating and clearing variables. Reuse 836 variables whenever possible, allocate or clear outside of loops, 837 pass temporary variables to subroutines instead of allocating them 838 inside the subroutines; 839 840 • use ‘mpfr_swap’ instead of ‘mpfr_set’ whenever possible. This will 841 avoid copying the significands; 842 843 • avoid using MPFR from C++, or make sure your C++ interface does not 844 perform unnecessary allocations or copies; 845 846 • MPFR functions work in-place: to compute ‘a = a + b’ you don’t need 847 an auxiliary variable, you can directly write ‘mpfr_add (a, a, b, 848 ...)’. 849 850 851File: mpfr.info, Node: MPFR Interface, Next: API Compatibility, Prev: MPFR Basics, Up: Top 852 8535 MPFR Interface 854**************** 855 856The floating-point functions expect arguments of type ‘mpfr_t’. 857 858 The MPFR floating-point functions have an interface that is similar 859to the GNU MP functions. The function prefix for floating-point 860operations is ‘mpfr_’. 861 862 The user has to specify the precision of each variable. A 863computation that assigns a variable will take place with the precision 864of the assigned variable; the cost of that computation should not depend 865on the precision of variables used as input (on average). 866 867 The semantics of a calculation in MPFR is specified as follows: 868Compute the requested operation exactly (with “infinite accuracy”), and 869round the result to the precision of the destination variable, with the 870given rounding mode. The MPFR floating-point functions are intended to 871be a smooth extension of the IEEE 754 arithmetic. The results obtained 872on a given computer are identical to those obtained on a computer with a 873different word size, or with a different compiler or operating system. 874 875 MPFR _does not keep track_ of the accuracy of a computation. This is 876left to the user or to a higher layer (for example the MPFI library for 877interval arithmetic). As a consequence, if two variables are used to 878store only a few significant bits, and their product is stored in a 879variable with large precision, then MPFR will still compute the result 880with full precision. 881 882 The value of the standard C macro ‘errno’ may be set to non-zero 883after calling any MPFR function or macro, whether or not there is an 884error. Except when documented, MPFR will not set ‘errno’, but functions 885called by the MPFR code (libc functions, memory allocator, etc.) may do 886so. 887 888* Menu: 889 890* Initialization Functions:: 891* Assignment Functions:: 892* Combined Initialization and Assignment Functions:: 893* Conversion Functions:: 894* Arithmetic Functions:: 895* Comparison Functions:: 896* Transcendental Functions:: 897* Input and Output Functions:: 898* Formatted Output Functions:: 899* Integer and Remainder Related Functions:: 900* Rounding-Related Functions:: 901* Miscellaneous Functions:: 902* Exception Related Functions:: 903* Memory Handling Functions:: 904* Compatibility with MPF:: 905* Custom Interface:: 906* Internals:: 907 908 909File: mpfr.info, Node: Initialization Functions, Next: Assignment Functions, Prev: MPFR Interface, Up: MPFR Interface 910 9115.1 Initialization Functions 912============================ 913 914An ‘mpfr_t’ object must be initialized before storing the first value in 915it. The functions ‘mpfr_init’ and ‘mpfr_init2’ are used for that 916purpose. 917 918 -- Function: void mpfr_init2 (mpfr_t X, mpfr_prec_t PREC) 919 Initialize X, set its precision to be *exactly* PREC bits and its 920 value to NaN. (Warning: the corresponding MPF function initializes 921 to zero instead.) 922 923 Normally, a variable should be initialized once only or at least be 924 cleared, using ‘mpfr_clear’, between initializations. To change 925 the precision of a variable that has already been initialized, use 926 ‘mpfr_set_prec’ or ‘mpfr_prec_round’; note that if the precision is 927 decreased, the unused memory will not be freed, so that it may be 928 wise to choose a large enough initial precision in order to avoid 929 reallocations. The precision PREC must be an integer between 930 ‘MPFR_PREC_MIN’ and ‘MPFR_PREC_MAX’ (otherwise the behavior is 931 undefined). 932 933 -- Function: void mpfr_inits2 (mpfr_prec_t PREC, mpfr_t X, ...) 934 Initialize all the ‘mpfr_t’ variables of the given variable 935 argument ‘va_list’, set their precision to be *exactly* PREC bits 936 and their value to NaN. See ‘mpfr_init2’ for more details. The 937 ‘va_list’ is assumed to be composed only of type ‘mpfr_t’ (or 938 equivalently ‘mpfr_ptr’). It begins from X, and ends when it 939 encounters a null pointer (whose type must also be ‘mpfr_ptr’). 940 941 -- Function: void mpfr_clear (mpfr_t X) 942 Free the space occupied by the significand of X. Make sure to call 943 this function for all ‘mpfr_t’ variables when you are done with 944 them. 945 946 -- Function: void mpfr_clears (mpfr_t X, ...) 947 Free the space occupied by all the ‘mpfr_t’ variables of the given 948 ‘va_list’. See ‘mpfr_clear’ for more details. The ‘va_list’ is 949 assumed to be composed only of type ‘mpfr_t’ (or equivalently 950 ‘mpfr_ptr’). It begins from X, and ends when it encounters a null 951 pointer (whose type must also be ‘mpfr_ptr’). 952 953 Here is an example of how to use multiple initialization functions 954(since ‘NULL’ is not necessarily defined in this context, we use 955‘(mpfr_ptr) 0’ instead, but ‘(mpfr_ptr) NULL’ is also correct). 956 957 { 958 mpfr_t x, y, z, t; 959 mpfr_inits2 (256, x, y, z, t, (mpfr_ptr) 0); 960 ... 961 mpfr_clears (x, y, z, t, (mpfr_ptr) 0); 962 } 963 964 -- Function: void mpfr_init (mpfr_t X) 965 Initialize X, set its precision to the default precision, and set 966 its value to NaN. The default precision can be changed by a call 967 to ‘mpfr_set_default_prec’. 968 969 Warning! In a given program, some other libraries might change the 970 default precision and not restore it. Thus it is safer to use 971 ‘mpfr_init2’. 972 973 -- Function: void mpfr_inits (mpfr_t X, ...) 974 Initialize all the ‘mpfr_t’ variables of the given ‘va_list’, set 975 their precision to the default precision and their value to NaN. 976 See ‘mpfr_init’ for more details. The ‘va_list’ is assumed to be 977 composed only of type ‘mpfr_t’ (or equivalently ‘mpfr_ptr’). It 978 begins from X, and ends when it encounters a null pointer (whose 979 type must also be ‘mpfr_ptr’). 980 981 Warning! In a given program, some other libraries might change the 982 default precision and not restore it. Thus it is safer to use 983 ‘mpfr_inits2’. 984 985 -- Macro: MPFR_DECL_INIT (NAME, PREC) 986 This macro declares NAME as an automatic variable of type ‘mpfr_t’, 987 initializes it and sets its precision to be *exactly* PREC bits and 988 its value to NaN. NAME must be a valid identifier. You must use 989 this macro in the declaration section. This macro is much faster 990 than using ‘mpfr_init2’ but has some drawbacks: 991 992 • You *must not* call ‘mpfr_clear’ with variables created with 993 this macro (the storage is allocated at the point of 994 declaration and deallocated when the brace-level is exited). 995 996 • You *cannot* change their precision. 997 998 • You *should not* create variables with huge precision with 999 this macro. 1000 1001 • Your compiler must support ‘Non-Constant Initializers’ 1002 (standard in C++ and ISO C99) and ‘Token Pasting’ (standard in 1003 ISO C89). If PREC is not a constant expression, your compiler 1004 must support ‘variable-length automatic arrays’ (standard in 1005 ISO C99). GCC 2.95.3 and above supports all these features. 1006 If you compile your program with GCC in C89 mode and with 1007 ‘-pedantic’, you may want to define the ‘MPFR_USE_EXTENSION’ 1008 macro to avoid warnings due to the ‘MPFR_DECL_INIT’ 1009 implementation. 1010 1011 -- Function: void mpfr_set_default_prec (mpfr_prec_t PREC) 1012 Set the default precision to be *exactly* PREC bits, where PREC can 1013 be any integer between ‘MPFR_PREC_MIN’ and ‘MPFR_PREC_MAX’. The 1014 precision of a variable means the number of bits used to store its 1015 significand. All subsequent calls to ‘mpfr_init’ or ‘mpfr_inits’ 1016 will use this precision, but previously initialized variables are 1017 unaffected. The default precision is set to 53 bits initially. 1018 1019 Note: when MPFR is built with the ‘--enable-thread-safe’ configure 1020 option, the default precision is local to each thread. *Note 1021 Memory Handling::, for more information. 1022 1023 -- Function: mpfr_prec_t mpfr_get_default_prec (void) 1024 Return the current default MPFR precision in bits. See the 1025 documentation of ‘mpfr_set_default_prec’. 1026 1027 Here is an example on how to initialize floating-point variables: 1028 1029 { 1030 mpfr_t x, y; 1031 mpfr_init (x); /* use default precision */ 1032 mpfr_init2 (y, 256); /* precision _exactly_ 256 bits */ 1033 ... 1034 /* When the program is about to exit, do ... */ 1035 mpfr_clear (x); 1036 mpfr_clear (y); 1037 mpfr_free_cache (); /* free the cache for constants like pi */ 1038 } 1039 1040 The following functions are useful for changing the precision during 1041a calculation. A typical use would be for adjusting the precision 1042gradually in iterative algorithms like Newton-Raphson, making the 1043computation precision closely match the actual accurate part of the 1044numbers. 1045 1046 -- Function: void mpfr_set_prec (mpfr_t X, mpfr_prec_t PREC) 1047 Set the precision of X to be *exactly* PREC bits, and set its value 1048 to NaN. The previous value stored in X is lost. It is equivalent 1049 to a call to ‘mpfr_clear(x)’ followed by a call to ‘mpfr_init2(x, 1050 prec)’, but more efficient as no allocation is done in case the 1051 current allocated space for the significand of X is enough. The 1052 precision PREC can be any integer between ‘MPFR_PREC_MIN’ and 1053 ‘MPFR_PREC_MAX’. In case you want to keep the previous value 1054 stored in X, use ‘mpfr_prec_round’ instead. 1055 1056 Warning! You must not use this function if X was initialized with 1057 ‘MPFR_DECL_INIT’ or with ‘mpfr_custom_init_set’ (*note Custom 1058 Interface::). 1059 1060 -- Function: mpfr_prec_t mpfr_get_prec (mpfr_t X) 1061 Return the precision of X, i.e., the number of bits used to store 1062 its significand. 1063 1064 1065File: mpfr.info, Node: Assignment Functions, Next: Combined Initialization and Assignment Functions, Prev: Initialization Functions, Up: MPFR Interface 1066 10675.2 Assignment Functions 1068======================== 1069 1070These functions assign new values to already initialized floats (*note 1071Initialization Functions::). 1072 1073 -- Function: int mpfr_set (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1074 -- Function: int mpfr_set_ui (mpfr_t ROP, unsigned long int OP, 1075 mpfr_rnd_t RND) 1076 -- Function: int mpfr_set_si (mpfr_t ROP, long int OP, mpfr_rnd_t RND) 1077 -- Function: int mpfr_set_uj (mpfr_t ROP, uintmax_t OP, mpfr_rnd_t RND) 1078 -- Function: int mpfr_set_sj (mpfr_t ROP, intmax_t OP, mpfr_rnd_t RND) 1079 -- Function: int mpfr_set_flt (mpfr_t ROP, float OP, mpfr_rnd_t RND) 1080 -- Function: int mpfr_set_d (mpfr_t ROP, double OP, mpfr_rnd_t RND) 1081 -- Function: int mpfr_set_ld (mpfr_t ROP, long double OP, mpfr_rnd_t 1082 RND) 1083 -- Function: int mpfr_set_float128 (mpfr_t ROP, _Float128 OP, 1084 mpfr_rnd_t RND) 1085 -- Function: int mpfr_set_decimal64 (mpfr_t ROP, _Decimal64 OP, 1086 mpfr_rnd_t RND) 1087 -- Function: int mpfr_set_decimal128 (mpfr_t ROP, _Decimal128 OP, 1088 mpfr_rnd_t RND) 1089 -- Function: int mpfr_set_z (mpfr_t ROP, mpz_t OP, mpfr_rnd_t RND) 1090 -- Function: int mpfr_set_q (mpfr_t ROP, mpq_t OP, mpfr_rnd_t RND) 1091 -- Function: int mpfr_set_f (mpfr_t ROP, mpf_t OP, mpfr_rnd_t RND) 1092 Set the value of ROP from OP, rounded toward the given direction 1093 RND. Note that the input 0 is converted to +0 by ‘mpfr_set_ui’, 1094 ‘mpfr_set_si’, ‘mpfr_set_uj’, ‘mpfr_set_sj’, The 1095 ‘mpfr_set_float128’ function is built only with the configure 1096 option ‘--enable-float128’, which requires the compiler or system 1097 provides the ‘_Float128’ data type (GCC 4.3 or later supports this 1098 data type); to use ‘mpfr_set_float128’, one should define the macro 1099 ‘MPFR_WANT_FLOAT128’ before including ‘mpfr.h’. ‘mpfr_set_z’, 1100 ‘mpfr_set_q’ and ‘mpfr_set_f’, regardless of the rounding mode. If 1101 the system does not support the IEEE 754 standard, ‘mpfr_set_flt’, 1102 ‘mpfr_set_d’, ‘mpfr_set_ld’, ‘mpfr_set_decimal64’ and 1103 ‘mpfr_set_decimal128’ might not preserve the signed zeros. The 1104 ‘mpfr_set_decimal64’ and ‘mpfr_set_decimal128’ functions are built 1105 only with the configure option ‘--enable-decimal-float’, and when 1106 the compiler or system provides the ‘_Decimal64’ and ‘_Decimal128’ 1107 data type; to use those functions, one should define the macro 1108 ‘MPFR_WANT_DECIMAL_FLOATS’ before including ‘mpfr.h’. ‘mpfr_set_q’ 1109 might fail if the numerator (or the denominator) cannot be 1110 represented as a ‘mpfr_t’. 1111 1112 For ‘mpfr_set’, the sign of a NaN is propagated in order to mimic 1113 the IEEE 754 ‘copy’ operation. But contrary to IEEE 754, the NaN 1114 flag is set as usual. 1115 1116 Note: If you want to store a floating-point constant to a ‘mpfr_t’, 1117 you should use ‘mpfr_set_str’ (or one of the MPFR constant 1118 functions, such as ‘mpfr_const_pi’ for Pi) instead of 1119 ‘mpfr_set_flt’, ‘mpfr_set_d’, ‘mpfr_set_ld’, ‘mpfr_set_decimal64’ 1120 or ‘mpfr_set_decimal128’. Otherwise the floating-point constant 1121 will be first converted into a reduced-precision (e.g., 53-bit) 1122 binary (or decimal, for ‘mpfr_set_decimal64’ and 1123 ‘mpfr_set_decimal128’) number before MPFR can work with it. 1124 1125 -- Function: int mpfr_set_ui_2exp (mpfr_t ROP, unsigned long int OP, 1126 mpfr_exp_t E, mpfr_rnd_t RND) 1127 -- Function: int mpfr_set_si_2exp (mpfr_t ROP, long int OP, mpfr_exp_t 1128 E, mpfr_rnd_t RND) 1129 -- Function: int mpfr_set_uj_2exp (mpfr_t ROP, uintmax_t OP, intmax_t 1130 E, mpfr_rnd_t RND) 1131 -- Function: int mpfr_set_sj_2exp (mpfr_t ROP, intmax_t OP, intmax_t E, 1132 mpfr_rnd_t RND) 1133 -- Function: int mpfr_set_z_2exp (mpfr_t ROP, mpz_t OP, mpfr_exp_t E, 1134 mpfr_rnd_t RND) 1135 Set the value of ROP from OP multiplied by two to the power E, 1136 rounded toward the given direction RND. Note that the input 0 is 1137 converted to +0. 1138 1139 -- Function: int mpfr_set_str (mpfr_t ROP, const char *S, int BASE, 1140 mpfr_rnd_t RND) 1141 Set ROP to the value of the string S in base BASE, rounded in the 1142 direction RND. See the documentation of ‘mpfr_strtofr’ for a 1143 detailed description of the valid string formats. Contrary to 1144 ‘mpfr_strtofr’, ‘mpfr_set_str’ requires the _whole_ string to 1145 represent a valid floating-point number. 1146 1147 The meaning of the return value differs from other MPFR functions: 1148 it is 0 if the entire string up to the final null character is a 1149 valid number in base BASE; otherwise it is −1, and ROP may have 1150 changed (users interested in the *note ternary value:: should use 1151 ‘mpfr_strtofr’ instead). 1152 1153 Note: it is preferable to use ‘mpfr_strtofr’ if one wants to 1154 distinguish between an infinite ROP value coming from an infinite S 1155 or from an overflow. 1156 1157 -- Function: int mpfr_strtofr (mpfr_t ROP, const char *NPTR, char 1158 **ENDPTR, int BASE, mpfr_rnd_t RND) 1159 Read a floating-point number from a string NPTR in base BASE, 1160 rounded in the direction RND; BASE must be either 0 (to detect the 1161 base, as described below) or a number from 2 to 62 (otherwise the 1162 behavior is undefined). If NPTR starts with valid data, the result 1163 is stored in ROP and ‘*ENDPTR’ points to the character just after 1164 the valid data (if ENDPTR is not a null pointer); otherwise ROP is 1165 set to zero (for consistency with ‘strtod’) and the value of NPTR 1166 is stored in the location referenced by ENDPTR (if ENDPTR is not a 1167 null pointer). The usual ternary value is returned. 1168 1169 Parsing follows the standard C ‘strtod’ function with some 1170 extensions. After optional leading whitespace, one has a subject 1171 sequence consisting of an optional sign (‘+’ or ‘-’), and either 1172 numeric data or special data. The subject sequence is defined as 1173 the longest initial subsequence of the input string, starting with 1174 the first non-whitespace character, that is of the expected form. 1175 1176 The form of numeric data is a non-empty sequence of significand 1177 digits with an optional decimal-point character, and an optional 1178 exponent consisting of an exponent prefix followed by an optional 1179 sign and a non-empty sequence of decimal digits. A significand 1180 digit is either a decimal digit or a Latin letter (62 possible 1181 characters), with ‘A’ = 10, ‘B’ = 11, ..., ‘Z’ = 35; case is 1182 ignored in bases less than or equal to 36, in bases larger than 36, 1183 ‘a’ = 36, ‘b’ = 37, ..., ‘z’ = 61. The value of a significand 1184 digit must be strictly less than the base. The decimal-point 1185 character can be either the one defined by the current locale or 1186 the period (the first one is accepted for consistency with the C 1187 standard and the practice, the second one is accepted to allow the 1188 programmer to provide MPFR numbers from strings in a way that does 1189 not depend on the current locale). The exponent prefix can be ‘e’ 1190 or ‘E’ for bases up to 10, or ‘@’ in any base; it indicates a 1191 multiplication by a power of the base. In bases 2 and 16, the 1192 exponent prefix can also be ‘p’ or ‘P’, in which case the exponent, 1193 called _binary exponent_, indicates a multiplication by a power of 1194 2 instead of the base (there is a difference only for base 16); in 1195 base 16 for example ‘1p2’ represents 4 whereas ‘1@2’ represents 1196 256. The value of an exponent is always written in base 10. 1197 1198 If the argument BASE is 0, then the base is automatically detected 1199 as follows. If the significand starts with ‘0b’ or ‘0B’, base 2 is 1200 assumed. If the significand starts with ‘0x’ or ‘0X’, base 16 is 1201 assumed. Otherwise base 10 is assumed. 1202 1203 Note: The exponent (if present) must contain at least a digit. 1204 Otherwise the possible exponent prefix and sign are not part of the 1205 number (which ends with the significand). Similarly, if ‘0b’, 1206 ‘0B’, ‘0x’ or ‘0X’ is not followed by a binary/hexadecimal digit, 1207 then the subject sequence stops at the character ‘0’, thus 0 is 1208 read. 1209 1210 Special data (for infinities and NaN) can be ‘@inf@’ or 1211 ‘@nan@(n-char-sequence-opt)’, and if BASE <= 16, it can also be 1212 ‘infinity’, ‘inf’, ‘nan’ or ‘nan(n-char-sequence-opt)’, all case 1213 insensitive. A ‘n-char-sequence-opt’ is a possibly empty string 1214 containing only digits, Latin letters and the underscore (0, 1, 2, 1215 ..., 9, a, b, ..., z, A, B, ..., Z, _). Note: one has an optional 1216 sign for all data, even NaN. For example, ‘-@nAn@(This_Is_Not_17)’ 1217 is a valid representation for NaN in base 17. 1218 1219 -- Function: void mpfr_set_nan (mpfr_t X) 1220 -- Function: void mpfr_set_inf (mpfr_t X, int SIGN) 1221 -- Function: void mpfr_set_zero (mpfr_t X, int SIGN) 1222 Set the variable X to NaN (Not-a-Number), infinity or zero 1223 respectively. In ‘mpfr_set_inf’ or ‘mpfr_set_zero’, X is set to 1224 plus infinity or plus zero iff SIGN is nonnegative; in 1225 ‘mpfr_set_nan’, the sign bit of the result is unspecified. 1226 1227 -- Function: void mpfr_swap (mpfr_t X, mpfr_t Y) 1228 Swap the structures pointed to by X and Y. In particular, the 1229 values are exchanged without rounding (this may be different from 1230 three ‘mpfr_set’ calls using a third auxiliary variable). 1231 1232 Warning! Since the precisions are exchanged, this will affect 1233 future assignments. Moreover, since the significand pointers are 1234 also exchanged, you must not use this function if the allocation 1235 method used for X and/or Y does not permit it. This is the case 1236 when X and/or Y were declared and initialized with 1237 ‘MPFR_DECL_INIT’, and possibly with ‘mpfr_custom_init_set’ (*note 1238 Custom Interface::). 1239 1240 1241File: mpfr.info, Node: Combined Initialization and Assignment Functions, Next: Conversion Functions, Prev: Assignment Functions, Up: MPFR Interface 1242 12435.3 Combined Initialization and Assignment Functions 1244==================================================== 1245 1246 -- Macro: int mpfr_init_set (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1247 -- Macro: int mpfr_init_set_ui (mpfr_t ROP, unsigned long int OP, 1248 mpfr_rnd_t RND) 1249 -- Macro: int mpfr_init_set_si (mpfr_t ROP, long int OP, mpfr_rnd_t 1250 RND) 1251 -- Macro: int mpfr_init_set_d (mpfr_t ROP, double OP, mpfr_rnd_t RND) 1252 -- Macro: int mpfr_init_set_ld (mpfr_t ROP, long double OP, mpfr_rnd_t 1253 RND) 1254 -- Macro: int mpfr_init_set_z (mpfr_t ROP, mpz_t OP, mpfr_rnd_t RND) 1255 -- Macro: int mpfr_init_set_q (mpfr_t ROP, mpq_t OP, mpfr_rnd_t RND) 1256 -- Macro: int mpfr_init_set_f (mpfr_t ROP, mpf_t OP, mpfr_rnd_t RND) 1257 Initialize ROP and set its value from OP, rounded in the direction 1258 RND. The precision of ROP will be taken from the active default 1259 precision, as set by ‘mpfr_set_default_prec’. 1260 1261 -- Function: int mpfr_init_set_str (mpfr_t X, const char *S, int BASE, 1262 mpfr_rnd_t RND) 1263 Initialize X and set its value from the string S in base BASE, 1264 rounded in the direction RND. See ‘mpfr_set_str’. 1265 1266 1267File: mpfr.info, Node: Conversion Functions, Next: Arithmetic Functions, Prev: Combined Initialization and Assignment Functions, Up: MPFR Interface 1268 12695.4 Conversion Functions 1270======================== 1271 1272 -- Function: float mpfr_get_flt (mpfr_t OP, mpfr_rnd_t RND) 1273 -- Function: double mpfr_get_d (mpfr_t OP, mpfr_rnd_t RND) 1274 -- Function: long double mpfr_get_ld (mpfr_t OP, mpfr_rnd_t RND) 1275 -- Function: _Float128 mpfr_get_float128 (mpfr_t OP, mpfr_rnd_t RND) 1276 -- Function: _Decimal64 mpfr_get_decimal64 (mpfr_t OP, mpfr_rnd_t RND) 1277 -- Function: _Decimal128 mpfr_get_decimal128 (mpfr_t OP, mpfr_rnd_t 1278 RND) 1279 Convert OP to a ‘float’ (respectively ‘double’, ‘long double’, 1280 ‘_Decimal64’, or ‘_Decimal128’) using the rounding mode RND. If OP 1281 is NaN, some fixed NaN (either quiet or signaling) or the result of 1282 0.0/0.0 is returned. If OP is ±Inf, an infinity of the same sign 1283 or the result of ±1.0/0.0 is returned. If OP is zero, these 1284 functions return a zero, trying to preserve its sign, if possible. 1285 The ‘mpfr_get_float128’, ‘mpfr_get_decimal64’ and 1286 ‘mpfr_get_decimal128’ functions are built only under some 1287 conditions: see the documentation of ‘mpfr_set_float128’, 1288 ‘mpfr_set_decimal64’ and ‘mpfr_set_decimal128’ respectively. 1289 1290 -- Function: long mpfr_get_si (mpfr_t OP, mpfr_rnd_t RND) 1291 -- Function: unsigned long mpfr_get_ui (mpfr_t OP, mpfr_rnd_t RND) 1292 -- Function: intmax_t mpfr_get_sj (mpfr_t OP, mpfr_rnd_t RND) 1293 -- Function: uintmax_t mpfr_get_uj (mpfr_t OP, mpfr_rnd_t RND) 1294 Convert OP to a ‘long’, an ‘unsigned long’, an ‘intmax_t’ or an 1295 ‘uintmax_t’ (respectively) after rounding it to an integer with 1296 respect to RND. If OP is NaN, 0 is returned and the _erange_ flag 1297 is set. If OP is too big for the return type, the function returns 1298 the maximum or the minimum of the corresponding C type, depending 1299 on the direction of the overflow; the _erange_ flag is set too. 1300 When there is no such range error, if the return value differs from 1301 OP, i.e., if OP is not an integer, the inexact flag is set. See 1302 also ‘mpfr_fits_slong_p’, ‘mpfr_fits_ulong_p’, ‘mpfr_fits_intmax_p’ 1303 and ‘mpfr_fits_uintmax_p’. 1304 1305 -- Function: double mpfr_get_d_2exp (long *EXP, mpfr_t OP, mpfr_rnd_t 1306 RND) 1307 -- Function: long double mpfr_get_ld_2exp (long *EXP, mpfr_t OP, 1308 mpfr_rnd_t RND) 1309 Return D and set EXP (formally, the value pointed to by EXP) such 1310 that 0.5<=abs(D)<1 and D times 2 raised to EXP equals OP rounded to 1311 double (resp. long double) precision, using the given rounding 1312 mode. If OP is zero, then a zero of the same sign (or an unsigned 1313 zero, if the implementation does not have signed zeros) is 1314 returned, and EXP is set to 0. If OP is NaN or an infinity, then 1315 the corresponding double precision (resp. long-double precision) 1316 value is returned, and EXP is undefined. 1317 1318 -- Function: int mpfr_frexp (mpfr_exp_t *EXP, mpfr_t Y, mpfr_t X, 1319 mpfr_rnd_t RND) 1320 Set EXP (formally, the value pointed to by EXP) and Y such that 1321 0.5<=abs(Y)<1 and Y times 2 raised to EXP equals X rounded to the 1322 precision of Y, using the given rounding mode. If X is zero, then 1323 Y is set to a zero of the same sign and EXP is set to 0. If X is 1324 NaN or an infinity, then Y is set to the same value and EXP is 1325 undefined. 1326 1327 -- Function: mpfr_exp_t mpfr_get_z_2exp (mpz_t ROP, mpfr_t OP) 1328 Put the scaled significand of OP (regarded as an integer, with the 1329 precision of OP) into ROP, and return the exponent EXP (which may 1330 be outside the current exponent range) such that OP exactly equals 1331 ROP times 2 raised to the power EXP. If OP is zero, the minimal 1332 exponent ‘emin’ is returned. If OP is NaN or an infinity, the 1333 _erange_ flag is set, ROP is set to 0, and the the minimal exponent 1334 ‘emin’ is returned. The returned exponent may be less than the 1335 minimal exponent ‘emin’ of MPFR numbers in the current exponent 1336 range; in case the exponent is not representable in the 1337 ‘mpfr_exp_t’ type, the _erange_ flag is set and the minimal value 1338 of the ‘mpfr_exp_t’ type is returned. 1339 1340 -- Function: int mpfr_get_z (mpz_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1341 Convert OP to a ‘mpz_t’, after rounding it with respect to RND. If 1342 OP is NaN or an infinity, the _erange_ flag is set, ROP is set to 1343 0, and 0 is returned. Otherwise the return value is zero when ROP 1344 is equal to OP (i.e., when OP is an integer), positive when it is 1345 greater than OP, and negative when it is smaller than OP; moreover, 1346 if ROP differs from OP, i.e., if OP is not an integer, the inexact 1347 flag is set. 1348 1349 -- Function: void mpfr_get_q (mpq_t ROP, mpfr_t OP) 1350 Convert OP to a ‘mpq_t’. If OP is NaN or an infinity, the _erange_ 1351 flag is set and ROP is set to 0. Otherwise the conversion is 1352 always exact. 1353 1354 -- Function: int mpfr_get_f (mpf_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1355 Convert OP to a ‘mpf_t’, after rounding it with respect to RND. 1356 The _erange_ flag is set if OP is NaN or an infinity, which do not 1357 exist in MPF. If OP is NaN, then ROP is undefined. If OP is +Inf 1358 (resp. −Inf), then ROP is set to the maximum (resp. minimum) value 1359 in the precision of the MPF number; if a future MPF version 1360 supports infinities, this behavior will be considered incorrect and 1361 will change (portable programs should assume that ROP is set either 1362 to this finite number or to an infinite number). Note that since 1363 MPFR currently has the same exponent type as MPF (but not with the 1364 same radix), the range of values is much larger in MPF than in 1365 MPFR, so that an overflow or underflow is not possible. 1366 1367 -- Function: size_t mpfr_get_str_ndigits (int B, mpfr_prec_t P) 1368 Return the minimal integer m such that any number of P bits, when 1369 output with m digits in radix B with rounding to nearest, can be 1370 recovered exactly when read again, still with rounding to nearest. 1371 More precisely, we have m = 1 + ceil(P*log(2)/log(B)), with P 1372 replaced by P−1 if B is a power of 2. 1373 1374 The argument B must be in the range 2 to 62; this is the range of 1375 bases supported by the ‘mpfr_get_str’ function. Note that contrary 1376 to the base argument of this function, negative values are not 1377 accepted. 1378 1379 -- Function: char * mpfr_get_str (char *STR, mpfr_exp_t *EXPPTR, int 1380 BASE, size_t N, mpfr_t OP, mpfr_rnd_t RND) 1381 Convert OP to a string of digits in base abs(BASE), with rounding 1382 in the direction RND, where N is either zero (see below) or the 1383 number of significant digits output in the string. The argument 1384 BASE may vary from 2 to 62 or from −2 to −36; otherwise the 1385 function does nothing and immediately returns a null pointer. 1386 1387 For BASE in the range 2 to 36, digits and lower-case letters are 1388 used; for −2 to −36, digits and upper-case letters are used; for 37 1389 to 62, digits, upper-case letters, and lower-case letters, in that 1390 significance order, are used. Warning! This implies that for BASE 1391 > 10, the successor of the digit 9 depends on BASE. This choice 1392 has been done for compatibility with GMP’s ‘mpf_get_str’ function. 1393 Users who wish a more consistent behavior should write a simple 1394 wrapper. 1395 1396 If the input is NaN, then the returned string is ‘@NaN@’ and the 1397 NaN flag is set. If the input is +Inf (resp. −Inf), then the 1398 returned string is ‘@Inf@’ (resp. ‘-@Inf@’). 1399 1400 If the input number is a finite number, the exponent is written 1401 through the pointer EXPPTR (for input 0, the current minimal 1402 exponent is written); the type ‘mpfr_exp_t’ is large enough to hold 1403 the exponent in all cases. 1404 1405 The generated string is a fraction, with an implicit radix point 1406 immediately to the left of the first digit. For example, the 1407 number −3.1416 would be returned as "−31416" in the string and 1 1408 written at EXPPTR. If RND is to nearest, and OP is exactly in the 1409 middle of two consecutive possible outputs, the one with an even 1410 significand is chosen, where both significands are considered with 1411 the exponent of OP. Note that for an odd base, this may not 1412 correspond to an even last digit: for example with 2 digits in base 1413 7, (14) and a half is rounded to (15) which is 12 in decimal, (16) 1414 and a half is rounded to (20) which is 14 in decimal, and (26) and 1415 a half is rounded to (26) which is 20 in decimal. 1416 1417 If N is zero, the number of digits of the significand is taken as 1418 ‘mpfr_get_str_ndigits(BASE,P)’ where P is the precision of OP 1419 (*note mpfr_get_str_ndigits::). 1420 1421 If STR is a null pointer, space for the significand is allocated 1422 using the allocation function (*note Memory Handling::) and a 1423 pointer to the string is returned (unless the base is invalid). To 1424 free the returned string, you must use ‘mpfr_free_str’. 1425 1426 If STR is not a null pointer, it should point to a block of storage 1427 large enough for the significand. A safe block size (sufficient 1428 for any value) is ‘max(N + 2, 7)’ if N is not zero; if N is zero, 1429 replace it by ‘mpfr_get_str_ndigits(BASE,P)’ where P is the 1430 precision of OP, as mentioned above. The extra two bytes are for a 1431 possible minus sign, and for the terminating null character, and 1432 the value 7 accounts for ‘-@Inf@’ plus the terminating null 1433 character. The pointer to the string STR is returned (unless the 1434 base is invalid). 1435 1436 Like in usual functions, the inexact flag is set iff the result is 1437 inexact. 1438 1439 -- Function: void mpfr_free_str (char *STR) 1440 Free a string allocated by ‘mpfr_get_str’ using the unallocation 1441 function (*note Memory Handling::). The block is assumed to be 1442 ‘strlen(STR)+1’ bytes. 1443 1444 -- Function: int mpfr_fits_ulong_p (mpfr_t OP, mpfr_rnd_t RND) 1445 -- Function: int mpfr_fits_slong_p (mpfr_t OP, mpfr_rnd_t RND) 1446 -- Function: int mpfr_fits_uint_p (mpfr_t OP, mpfr_rnd_t RND) 1447 -- Function: int mpfr_fits_sint_p (mpfr_t OP, mpfr_rnd_t RND) 1448 -- Function: int mpfr_fits_ushort_p (mpfr_t OP, mpfr_rnd_t RND) 1449 -- Function: int mpfr_fits_sshort_p (mpfr_t OP, mpfr_rnd_t RND) 1450 -- Function: int mpfr_fits_uintmax_p (mpfr_t OP, mpfr_rnd_t RND) 1451 -- Function: int mpfr_fits_intmax_p (mpfr_t OP, mpfr_rnd_t RND) 1452 Return non-zero if OP would fit in the respective C data type, 1453 respectively ‘unsigned long’, ‘long’, ‘unsigned int’, ‘int’, 1454 ‘unsigned short’, ‘short’, ‘uintmax_t’, ‘intmax_t’, when rounded to 1455 an integer in the direction RND. For instance, with the 1456 ‘MPFR_RNDU’ rounding mode on −0.5, the result will be non-zero for 1457 all these functions. For ‘MPFR_RNDF’, those functions return 1458 non-zero when it is guaranteed that the corresponding conversion 1459 function (for example ‘mpfr_get_ui’ for ‘mpfr_fits_ulong_p’), when 1460 called with faithful rounding, will always return a number that is 1461 representable in the corresponding type. As a consequence, for 1462 ‘MPFR_RNDF’, ‘mpfr_fits_ulong_p’ will return non-zero for a 1463 non-negative number less than or equal to ‘ULONG_MAX’. 1464 1465 1466File: mpfr.info, Node: Arithmetic Functions, Next: Comparison Functions, Prev: Conversion Functions, Up: MPFR Interface 1467 14685.5 Arithmetic Functions 1469======================== 1470 1471 -- Function: int mpfr_add (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, 1472 mpfr_rnd_t RND) 1473 -- Function: int mpfr_add_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int 1474 OP2, mpfr_rnd_t RND) 1475 -- Function: int mpfr_add_si (mpfr_t ROP, mpfr_t OP1, long int OP2, 1476 mpfr_rnd_t RND) 1477 -- Function: int mpfr_add_d (mpfr_t ROP, mpfr_t OP1, double OP2, 1478 mpfr_rnd_t RND) 1479 -- Function: int mpfr_add_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2, 1480 mpfr_rnd_t RND) 1481 -- Function: int mpfr_add_q (mpfr_t ROP, mpfr_t OP1, mpq_t OP2, 1482 mpfr_rnd_t RND) 1483 Set ROP to OP1 + OP2 rounded in the direction RND. The IEEE 754 1484 rules are used, in particular for signed zeros. But for types 1485 having no signed zeros, 0 is considered unsigned (i.e., (+0) + 0 = 1486 (+0) and (−0) + 0 = (−0)). The ‘mpfr_add_d’ function assumes that 1487 the radix of the ‘double’ type is a power of 2, with a precision at 1488 most that declared by the C implementation (macro 1489 ‘IEEE_DBL_MANT_DIG’, and if not defined 53 bits). 1490 1491 -- Function: int mpfr_sub (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, 1492 mpfr_rnd_t RND) 1493 -- Function: int mpfr_ui_sub (mpfr_t ROP, unsigned long int OP1, mpfr_t 1494 OP2, mpfr_rnd_t RND) 1495 -- Function: int mpfr_sub_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int 1496 OP2, mpfr_rnd_t RND) 1497 -- Function: int mpfr_si_sub (mpfr_t ROP, long int OP1, mpfr_t OP2, 1498 mpfr_rnd_t RND) 1499 -- Function: int mpfr_sub_si (mpfr_t ROP, mpfr_t OP1, long int OP2, 1500 mpfr_rnd_t RND) 1501 -- Function: int mpfr_d_sub (mpfr_t ROP, double OP1, mpfr_t OP2, 1502 mpfr_rnd_t RND) 1503 -- Function: int mpfr_sub_d (mpfr_t ROP, mpfr_t OP1, double OP2, 1504 mpfr_rnd_t RND) 1505 -- Function: int mpfr_z_sub (mpfr_t ROP, mpz_t OP1, mpfr_t OP2, 1506 mpfr_rnd_t RND) 1507 -- Function: int mpfr_sub_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2, 1508 mpfr_rnd_t RND) 1509 -- Function: int mpfr_sub_q (mpfr_t ROP, mpfr_t OP1, mpq_t OP2, 1510 mpfr_rnd_t RND) 1511 Set ROP to OP1 - OP2 rounded in the direction RND. The IEEE 754 1512 rules are used, in particular for signed zeros. But for types 1513 having no signed zeros, 0 is considered unsigned (i.e., (+0) − 0 = 1514 (+0), (−0) − 0 = (−0), 0 − (+0) = (−0) and 0 − (−0) = (+0)). The 1515 same restrictions than for ‘mpfr_add_d’ apply to ‘mpfr_d_sub’ and 1516 ‘mpfr_sub_d’. 1517 1518 -- Function: int mpfr_mul (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, 1519 mpfr_rnd_t RND) 1520 -- Function: int mpfr_mul_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int 1521 OP2, mpfr_rnd_t RND) 1522 -- Function: int mpfr_mul_si (mpfr_t ROP, mpfr_t OP1, long int OP2, 1523 mpfr_rnd_t RND) 1524 -- Function: int mpfr_mul_d (mpfr_t ROP, mpfr_t OP1, double OP2, 1525 mpfr_rnd_t RND) 1526 -- Function: int mpfr_mul_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2, 1527 mpfr_rnd_t RND) 1528 -- Function: int mpfr_mul_q (mpfr_t ROP, mpfr_t OP1, mpq_t OP2, 1529 mpfr_rnd_t RND) 1530 Set ROP to OP1 times OP2 rounded in the direction RND. When a 1531 result is zero, its sign is the product of the signs of the 1532 operands (for types having no signed zeros, 0 is considered 1533 positive). The same restrictions than for ‘mpfr_add_d’ apply to 1534 ‘mpfr_mul_d’. 1535 1536 -- Function: int mpfr_sqr (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1537 Set ROP to the square of OP rounded in the direction RND. 1538 1539 -- Function: int mpfr_div (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, 1540 mpfr_rnd_t RND) 1541 -- Function: int mpfr_ui_div (mpfr_t ROP, unsigned long int OP1, mpfr_t 1542 OP2, mpfr_rnd_t RND) 1543 -- Function: int mpfr_div_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int 1544 OP2, mpfr_rnd_t RND) 1545 -- Function: int mpfr_si_div (mpfr_t ROP, long int OP1, mpfr_t OP2, 1546 mpfr_rnd_t RND) 1547 -- Function: int mpfr_div_si (mpfr_t ROP, mpfr_t OP1, long int OP2, 1548 mpfr_rnd_t RND) 1549 -- Function: int mpfr_d_div (mpfr_t ROP, double OP1, mpfr_t OP2, 1550 mpfr_rnd_t RND) 1551 -- Function: int mpfr_div_d (mpfr_t ROP, mpfr_t OP1, double OP2, 1552 mpfr_rnd_t RND) 1553 -- Function: int mpfr_div_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2, 1554 mpfr_rnd_t RND) 1555 -- Function: int mpfr_div_q (mpfr_t ROP, mpfr_t OP1, mpq_t OP2, 1556 mpfr_rnd_t RND) 1557 Set ROP to OP1/OP2 rounded in the direction RND. When a result is 1558 zero, its sign is the product of the signs of the operands. For 1559 types having no signed zeros, 0 is considered positive; but note 1560 that if OP1 is non-zero and OP2 is zero, the result might change 1561 from ±Inf to NaN in future MPFR versions if there is an opposite 1562 decision on the IEEE 754 side. The same restrictions than for 1563 ‘mpfr_add_d’ apply to ‘mpfr_d_div’ and ‘mpfr_div_d’. 1564 1565 -- Function: int mpfr_sqrt (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1566 -- Function: int mpfr_sqrt_ui (mpfr_t ROP, unsigned long int OP, 1567 mpfr_rnd_t RND) 1568 Set ROP to the square root of OP rounded in the direction RND. Set 1569 ROP to −0 if OP is −0, to be consistent with the IEEE 754 standard. 1570 Set ROP to NaN if OP is negative. 1571 1572 -- Function: int mpfr_rec_sqrt (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1573 Set ROP to the reciprocal square root of OP rounded in the 1574 direction RND. Set ROP to +Inf if OP is ±0, +0 if OP is +Inf, and 1575 NaN if OP is negative. Warning! Therefore the result on −0 is 1576 different from the one of the rSqrt function recommended by the 1577 IEEE 754-2008 standard (Section 9.2.1), which is −Inf instead of 1578 +Inf. 1579 1580 -- Function: int mpfr_cbrt (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1581 -- Function: int mpfr_rootn_ui (mpfr_t ROP, mpfr_t OP, unsigned long 1582 int N, mpfr_rnd_t RND) 1583 Set ROP to the Nth root (with N = 3, the cubic root, for 1584 ‘mpfr_cbrt’) of OP rounded in the direction RND. For N = 0, set 1585 ROP to NaN. For N odd (resp. even) and OP negative (including 1586 −Inf), set ROP to a negative number (resp. NaN). If OP is zero, 1587 set ROP to zero with the sign obtained by the usual limit rules, 1588 i.e., the same sign as OP if N is odd, and positive if N is even. 1589 1590 These functions agree with the rootn function of the IEEE 754-2008 1591 standard and the P754/D2.41 draft of the next standard 1592 (Section 9.2). Note that it is here restricted to N >= 0. 1593 Functions allowing a negative N may be implemented in the future. 1594 1595 -- Function: int mpfr_root (mpfr_t ROP, mpfr_t OP, unsigned long int N, 1596 mpfr_rnd_t RND) 1597 This function is the same as ‘mpfr_rootn_ui’ except when OP is −0 1598 and N is even: the result is −0 instead of +0 (the reason was to be 1599 consistent with ‘mpfr_sqrt’). Said otherwise, if OP is zero, set 1600 ROP to OP. 1601 1602 This function predates the IEEE 754-2008 standard and behaves 1603 differently from its rootn function. It is marked as deprecated 1604 and will be removed in a future release. 1605 1606 -- Function: int mpfr_neg (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1607 -- Function: int mpfr_abs (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1608 Set ROP to -OP and the absolute value of OP respectively, rounded 1609 in the direction RND. Just changes or adjusts the sign if ROP and 1610 OP are the same variable, otherwise a rounding might occur if the 1611 precision of ROP is less than that of OP. 1612 1613 The sign rule also applies to NaN in order to mimic the IEEE 754 1614 ‘negate’ and ‘abs’ operations, i.e., for ‘mpfr_neg’, the sign is 1615 reversed, and for ‘mpfr_abs’, the sign is set to positive. But 1616 contrary to IEEE 754, the NaN flag is set as usual. 1617 1618 -- Function: int mpfr_dim (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, 1619 mpfr_rnd_t RND) 1620 Set ROP to the positive difference of OP1 and OP2, i.e., OP1 - OP2 1621 rounded in the direction RND if OP1 > OP2, +0 if OP1 <= OP2, and 1622 NaN if OP1 or OP2 is NaN. 1623 1624 -- Function: int mpfr_mul_2ui (mpfr_t ROP, mpfr_t OP1, unsigned long 1625 int OP2, mpfr_rnd_t RND) 1626 -- Function: int mpfr_mul_2si (mpfr_t ROP, mpfr_t OP1, long int OP2, 1627 mpfr_rnd_t RND) 1628 Set ROP to OP1 times 2 raised to OP2 rounded in the direction RND. 1629 Just increases the exponent by OP2 when ROP and OP1 are identical. 1630 1631 -- Function: int mpfr_div_2ui (mpfr_t ROP, mpfr_t OP1, unsigned long 1632 int OP2, mpfr_rnd_t RND) 1633 -- Function: int mpfr_div_2si (mpfr_t ROP, mpfr_t OP1, long int OP2, 1634 mpfr_rnd_t RND) 1635 Set ROP to OP1 divided by 2 raised to OP2 rounded in the direction 1636 RND. Just decreases the exponent by OP2 when ROP and OP1 are 1637 identical. 1638 1639 -- Function: int mpfr_fac_ui (mpfr_t ROP, unsigned long int OP, 1640 mpfr_rnd_t RND) 1641 Set ROP to the factorial of OP, rounded in the direction RND. 1642 1643 -- Function: int mpfr_fma (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, mpfr_t 1644 OP3, mpfr_rnd_t RND) 1645 -- Function: int mpfr_fms (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, mpfr_t 1646 OP3, mpfr_rnd_t RND) 1647 Set ROP to (OP1 times OP2) + OP3 (resp. (OP1 times OP2) - OP3) 1648 rounded in the direction RND. Concerning special values (signed 1649 zeros, infinities, NaN), these functions behave like a 1650 multiplication followed by a separate addition or subtraction. 1651 That is, the fused operation matters only for rounding. 1652 1653 -- Function: int mpfr_fmma (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, mpfr_t 1654 OP3, mpfr_t OP4, mpfr_rnd_t RND) 1655 -- Function: int mpfr_fmms (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, mpfr_t 1656 OP3, mpfr_t OP4, mpfr_rnd_t RND) 1657 Set ROP to (OP1 times OP2) + (OP3 times OP4) (resp. (OP1 times OP2) 1658 - (OP3 times OP4)) rounded in the direction RND. In case the 1659 computation of OP1 times OP2 overflows or underflows (or that of 1660 OP3 times OP4), the result ROP is computed as if the two 1661 intermediate products were computed with rounding toward zero. 1662 1663 -- Function: int mpfr_hypot (mpfr_t ROP, mpfr_t X, mpfr_t Y, mpfr_rnd_t 1664 RND) 1665 Set ROP to the Euclidean norm of X and Y, i.e., the square root of 1666 the sum of the squares of X and Y, rounded in the direction RND. 1667 Special values are handled as described in the ISO C99 1668 (Section F.9.4.3) and IEEE 754-2008 (Section 9.2.1) standards: If X 1669 or Y is an infinity, then +Inf is returned in ROP, even if the 1670 other number is NaN. 1671 1672 -- Function: int mpfr_sum (mpfr_t ROP, const mpfr_ptr TAB[], unsigned 1673 long int N, mpfr_rnd_t RND) 1674 Set ROP to the sum of all elements of TAB, whose size is N, 1675 correctly rounded in the direction RND. Warning: for efficiency 1676 reasons, TAB is an array of pointers to ‘mpfr_t’, not an array of 1677 ‘mpfr_t’. If N = 0, then the result is +0, and if N = 1, then the 1678 function is equivalent to ‘mpfr_set’. For the special exact cases, 1679 the result is the same as the one obtained with a succession of 1680 additions (‘mpfr_add’) in infinite precision. In particular, if 1681 the result is an exact zero and N >= 1: 1682 • if all the inputs have the same sign (i.e., all +0 or all −0), 1683 then the result has the same sign as the inputs; 1684 • otherwise, either because all inputs are zeros with at least a 1685 +0 and a −0, or because some inputs are non-zero (but they 1686 globally cancel), the result is +0, except for the ‘MPFR_RNDD’ 1687 rounding mode, where it is −0. 1688 1689 -- Function: int mpfr_dot (mpfr_t ROP, const mpfr_ptr A[], const 1690 mpfr_ptr B[], unsigned long int N, mpfr_rnd_t RND) 1691 Set ROP to the dot product of elements of A by those of B, whose 1692 common size is N, correctly rounded in the direction RND. Warning: 1693 for efficiency reasons, A and B are arrays of pointers to ‘mpfr_t’. 1694 This function is experimental, and does not yet handle intermediate 1695 overflows and underflows. 1696 1697 For the power functions (with an integer exponent or not), see *note 1698mpfr_pow:: in *note Transcendental Functions::. 1699 1700 1701File: mpfr.info, Node: Comparison Functions, Next: Transcendental Functions, Prev: Arithmetic Functions, Up: MPFR Interface 1702 17035.6 Comparison Functions 1704======================== 1705 1706 -- Function: int mpfr_cmp (mpfr_t OP1, mpfr_t OP2) 1707 -- Function: int mpfr_cmp_ui (mpfr_t OP1, unsigned long int OP2) 1708 -- Function: int mpfr_cmp_si (mpfr_t OP1, long int OP2) 1709 -- Function: int mpfr_cmp_d (mpfr_t OP1, double OP2) 1710 -- Function: int mpfr_cmp_ld (mpfr_t OP1, long double OP2) 1711 -- Function: int mpfr_cmp_z (mpfr_t OP1, mpz_t OP2) 1712 -- Function: int mpfr_cmp_q (mpfr_t OP1, mpq_t OP2) 1713 -- Function: int mpfr_cmp_f (mpfr_t OP1, mpf_t OP2) 1714 Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero if 1715 OP1 = OP2, and a negative value if OP1 < OP2. Both OP1 and OP2 are 1716 considered to their full own precision, which may differ. If one 1717 of the operands is NaN, set the _erange_ flag and return zero. 1718 1719 Note: These functions may be useful to distinguish the three 1720 possible cases. If you need to distinguish two cases only, it is 1721 recommended to use the predicate functions (e.g., ‘mpfr_equal_p’ 1722 for the equality) described below; they behave like the IEEE 754 1723 comparisons, in particular when one or both arguments are NaN. But 1724 only floating-point numbers can be compared (you may need to do a 1725 conversion first). 1726 1727 -- Function: int mpfr_cmp_ui_2exp (mpfr_t OP1, unsigned long int OP2, 1728 mpfr_exp_t E) 1729 -- Function: int mpfr_cmp_si_2exp (mpfr_t OP1, long int OP2, mpfr_exp_t 1730 E) 1731 Compare OP1 and OP2 multiplied by two to the power E. Similar as 1732 above. 1733 1734 -- Function: int mpfr_cmpabs (mpfr_t OP1, mpfr_t OP2) 1735 -- Function: int mpfr_cmpabs_ui (mpfr_t OP1, unsigned long OP2) 1736 Compare |OP1| and |OP2|. Return a positive value if |OP1| > |OP2|, 1737 zero if |OP1| = |OP2|, and a negative value if |OP1| < |OP2|. If 1738 one of the operands is NaN, set the _erange_ flag and return zero. 1739 1740 -- Function: int mpfr_nan_p (mpfr_t OP) 1741 -- Function: int mpfr_inf_p (mpfr_t OP) 1742 -- Function: int mpfr_number_p (mpfr_t OP) 1743 -- Function: int mpfr_zero_p (mpfr_t OP) 1744 -- Function: int mpfr_regular_p (mpfr_t OP) 1745 Return non-zero if OP is respectively NaN, an infinity, an ordinary 1746 number (i.e., neither NaN nor an infinity), zero, or a regular 1747 number (i.e., neither NaN, nor an infinity nor zero). Return zero 1748 otherwise. 1749 1750 -- Macro: int mpfr_sgn (mpfr_t OP) 1751 Return a positive value if OP > 0, zero if OP = 0, and a negative 1752 value if OP < 0. If the operand is NaN, set the _erange_ flag and 1753 return zero. This is equivalent to ‘mpfr_cmp_ui (op, 0)’, but more 1754 efficient. 1755 1756 -- Function: int mpfr_greater_p (mpfr_t OP1, mpfr_t OP2) 1757 -- Function: int mpfr_greaterequal_p (mpfr_t OP1, mpfr_t OP2) 1758 -- Function: int mpfr_less_p (mpfr_t OP1, mpfr_t OP2) 1759 -- Function: int mpfr_lessequal_p (mpfr_t OP1, mpfr_t OP2) 1760 -- Function: int mpfr_equal_p (mpfr_t OP1, mpfr_t OP2) 1761 Return non-zero if OP1 > OP2, OP1 >= OP2, OP1 < OP2, OP1 <= OP2, 1762 OP1 = OP2 respectively, and zero otherwise. Those functions return 1763 zero whenever OP1 and/or OP2 is NaN. 1764 1765 -- Function: int mpfr_lessgreater_p (mpfr_t OP1, mpfr_t OP2) 1766 Return non-zero if OP1 < OP2 or OP1 > OP2 (i.e., neither OP1, nor 1767 OP2 is NaN, and OP1 <> OP2), zero otherwise (i.e., OP1 and/or OP2 1768 is NaN, or OP1 = OP2). 1769 1770 -- Function: int mpfr_unordered_p (mpfr_t OP1, mpfr_t OP2) 1771 Return non-zero if OP1 or OP2 is a NaN (i.e., they cannot be 1772 compared), zero otherwise. 1773 1774 -- Function: int mpfr_total_order_p (mpfr_t X, mpfr_t Y) 1775 This function implements the totalOrder predicate from 1776 IEEE 754-2008, where −NaN < −Inf < negative finite numbers < −0 < 1777 +0 < positive finite numbers < +Inf < +NaN. It returns a non-zero 1778 value (true) when X is smaller than or equal to Y for this order 1779 relation, and zero (false) otherwise. Contrary to ‘mpfr_cmp (x, 1780 y)’, which returns a ternary value, ‘mpfr_total_order_p’ returns a 1781 binary value (zero or non-zero). In particular, 1782 ‘mpfr_total_order_p (x, x)’ returns true, ‘mpfr_total_order_p (-0, 1783 +0)’ returns true and ‘mpfr_total_order_p (+0, -0)’ returns false. 1784 The sign bit of NaN also matters. 1785 1786 1787File: mpfr.info, Node: Transcendental Functions, Next: Input and Output Functions, Prev: Comparison Functions, Up: MPFR Interface 1788 17895.7 Transcendental Functions 1790============================ 1791 1792All those functions, except explicitly stated (for example 1793‘mpfr_sin_cos’), return a *note ternary value::, i.e., zero for an exact 1794return value, a positive value for a return value larger than the exact 1795result, and a negative value otherwise. 1796 1797 Important note: In some domains, computing transcendental functions 1798(even more with correct rounding) is expensive, even in small precision, 1799for example the trigonometric and Bessel functions with a large 1800argument. For some functions, the algorithm complexity and memory usage 1801does not depend only on the output precision: for instance, the memory 1802usage of ‘mpfr_rootn_ui’ is also linear in the argument K, and the 1803memory usage of the incomplete Gamma function also depends on the 1804precision of the input OP. It is also theoretically possible that some 1805functions on some particular inputs might be very hard to round (i.e. 1806the Table Maker’s Dilemma occurs in much larger precisions than normally 1807expected from the context), meaning that the internal precision needs to 1808be increased even more; but it is conjectured that the needed precision 1809has a reasonable bound. 1810 1811 -- Function: int mpfr_log (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1812 -- Function: int mpfr_log_ui (mpfr_t ROP, unsigned long OP, mpfr_rnd_t 1813 RND) 1814 -- Function: int mpfr_log2 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1815 -- Function: int mpfr_log10 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1816 Set ROP to the natural logarithm of OP, log2(OP) or log10(OP), 1817 respectively, rounded in the direction RND. Set ROP to +0 if OP is 1818 1 (in all rounding modes), for consistency with the ISO C99 and 1819 IEEE 754-2008 standards. Set ROP to −Inf if OP is ±0 (i.e., the 1820 sign of the zero has no influence on the result). 1821 1822 -- Function: int mpfr_log1p (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1823 Set ROP to the logarithm of one plus OP, rounded in the direction 1824 RND. Set ROP to −Inf if OP is −1. 1825 1826 -- Function: int mpfr_exp (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1827 -- Function: int mpfr_exp2 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1828 -- Function: int mpfr_exp10 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1829 Set ROP to the exponential of OP, to 2 power of OP or to 10 power 1830 of OP, respectively, rounded in the direction RND. 1831 1832 -- Function: int mpfr_expm1 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1833 Set ROP to the exponential of OP followed by a subtraction by one, 1834 rounded in the direction RND. 1835 1836 -- Function: int mpfr_pow (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, 1837 mpfr_rnd_t RND) 1838 -- Function: int mpfr_pow_ui (mpfr_t ROP, mpfr_t OP1, unsigned long int 1839 OP2, mpfr_rnd_t RND) 1840 -- Function: int mpfr_pow_si (mpfr_t ROP, mpfr_t OP1, long int OP2, 1841 mpfr_rnd_t RND) 1842 -- Function: int mpfr_pow_z (mpfr_t ROP, mpfr_t OP1, mpz_t OP2, 1843 mpfr_rnd_t RND) 1844 -- Function: int mpfr_ui_pow_ui (mpfr_t ROP, unsigned long int OP1, 1845 unsigned long int OP2, mpfr_rnd_t RND) 1846 -- Function: int mpfr_ui_pow (mpfr_t ROP, unsigned long int OP1, mpfr_t 1847 OP2, mpfr_rnd_t RND) 1848 Set ROP to OP1 raised to OP2, rounded in the direction RND. 1849 Special values are handled as described in the ISO C99 and 1850 IEEE 754-2008 standards for the ‘pow’ function: 1851 • ‘pow(±0, Y)’ returns plus or minus infinity for Y a negative 1852 odd integer. 1853 • ‘pow(±0, Y)’ returns plus infinity for Y negative and not an 1854 odd integer. 1855 • ‘pow(±0, Y)’ returns plus or minus zero for Y a positive odd 1856 integer. 1857 • ‘pow(±0, Y)’ returns plus zero for Y positive and not an odd 1858 integer. 1859 • ‘pow(-1, ±Inf)’ returns 1. 1860 • ‘pow(+1, Y)’ returns 1 for any Y, even a NaN. 1861 • ‘pow(X, ±0)’ returns 1 for any X, even a NaN. 1862 • ‘pow(X, Y)’ returns NaN for finite negative X and finite 1863 non-integer Y. 1864 • ‘pow(X, -Inf)’ returns plus infinity for 0 < abs(x) < 1, and 1865 plus zero for abs(x) > 1. 1866 • ‘pow(X, +Inf)’ returns plus zero for 0 < abs(x) < 1, and plus 1867 infinity for abs(x) > 1. 1868 • ‘pow(-Inf, Y)’ returns minus zero for Y a negative odd 1869 integer. 1870 • ‘pow(-Inf, Y)’ returns plus zero for Y negative and not an odd 1871 integer. 1872 • ‘pow(-Inf, Y)’ returns minus infinity for Y a positive odd 1873 integer. 1874 • ‘pow(-Inf, Y)’ returns plus infinity for Y positive and not an 1875 odd integer. 1876 • ‘pow(+Inf, Y)’ returns plus zero for Y negative, and plus 1877 infinity for Y positive. 1878 Note: When 0 is of integer type, it is regarded as +0 by these 1879 functions. We do not use the usual limit rules in this case, as 1880 these rules are not used for ‘pow’. 1881 1882 -- Function: int mpfr_cos (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1883 -- Function: int mpfr_sin (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1884 -- Function: int mpfr_tan (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1885 Set ROP to the cosine of OP, sine of OP, tangent of OP, rounded in 1886 the direction RND. 1887 1888 -- Function: int mpfr_sin_cos (mpfr_t SOP, mpfr_t COP, mpfr_t OP, 1889 mpfr_rnd_t RND) 1890 Set simultaneously SOP to the sine of OP and COP to the cosine of 1891 OP, rounded in the direction RND with the corresponding precisions 1892 of SOP and COP, which must be different variables. Return 0 iff 1893 both results are exact, more precisely it returns s+4c where s=0 if 1894 SOP is exact, s=1 if SOP is larger than the sine of OP, s=2 if SOP 1895 is smaller than the sine of OP, and similarly for c and the cosine 1896 of OP. 1897 1898 -- Function: int mpfr_sec (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1899 -- Function: int mpfr_csc (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1900 -- Function: int mpfr_cot (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1901 Set ROP to the secant of OP, cosecant of OP, cotangent of OP, 1902 rounded in the direction RND. 1903 1904 -- Function: int mpfr_acos (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1905 -- Function: int mpfr_asin (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1906 -- Function: int mpfr_atan (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1907 Set ROP to the arc-cosine, arc-sine or arc-tangent of OP, rounded 1908 in the direction RND. Note that since ‘acos(-1)’ returns the 1909 floating-point number closest to Pi according to the given rounding 1910 mode, this number might not be in the output range 0 <= ROP < Pi of 1911 the arc-cosine function; still, the result lies in the image of the 1912 output range by the rounding function. The same holds for 1913 ‘asin(-1)’, ‘asin(1)’, ‘atan(-Inf)’, ‘atan(+Inf)’ or for ‘atan(op)’ 1914 with large OP and small precision of ROP. 1915 1916 -- Function: int mpfr_atan2 (mpfr_t ROP, mpfr_t Y, mpfr_t X, mpfr_rnd_t 1917 RND) 1918 Set ROP to the arc-tangent2 of Y and X, rounded in the direction 1919 RND: if ‘x > 0’, ‘atan2(y, x) = atan(y/x)’; if ‘x < 0’, ‘atan2(y, 1920 x) = sign(y)*(Pi - atan(abs(y/x)))’, thus a number from -Pi to Pi. 1921 As for ‘atan’, in case the exact mathematical result is +Pi or -Pi, 1922 its rounded result might be outside the function output range. 1923 1924 ‘atan2(y, 0)’ does not raise any floating-point exception. Special 1925 values are handled as described in the ISO C99 and IEEE 754-2008 1926 standards for the ‘atan2’ function: 1927 • ‘atan2(+0, -0)’ returns +Pi. 1928 • ‘atan2(-0, -0)’ returns -Pi. 1929 • ‘atan2(+0, +0)’ returns +0. 1930 • ‘atan2(-0, +0)’ returns −0. 1931 • ‘atan2(+0, x)’ returns +Pi for x < 0. 1932 • ‘atan2(-0, x)’ returns -Pi for x < 0. 1933 • ‘atan2(+0, x)’ returns +0 for x > 0. 1934 • ‘atan2(-0, x)’ returns −0 for x > 0. 1935 • ‘atan2(y, 0)’ returns -Pi/2 for y < 0. 1936 • ‘atan2(y, 0)’ returns +Pi/2 for y > 0. 1937 • ‘atan2(+Inf, -Inf)’ returns +3*Pi/4. 1938 • ‘atan2(-Inf, -Inf)’ returns -3*Pi/4. 1939 • ‘atan2(+Inf, +Inf)’ returns +Pi/4. 1940 • ‘atan2(-Inf, +Inf)’ returns -Pi/4. 1941 • ‘atan2(+Inf, x)’ returns +Pi/2 for finite x. 1942 • ‘atan2(-Inf, x)’ returns -Pi/2 for finite x. 1943 • ‘atan2(y, -Inf)’ returns +Pi for finite y > 0. 1944 • ‘atan2(y, -Inf)’ returns -Pi for finite y < 0. 1945 • ‘atan2(y, +Inf)’ returns +0 for finite y > 0. 1946 • ‘atan2(y, +Inf)’ returns −0 for finite y < 0. 1947 1948 -- Function: int mpfr_cosh (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1949 -- Function: int mpfr_sinh (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1950 -- Function: int mpfr_tanh (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1951 Set ROP to the hyperbolic cosine, sine or tangent of OP, rounded in 1952 the direction RND. 1953 1954 -- Function: int mpfr_sinh_cosh (mpfr_t SOP, mpfr_t COP, mpfr_t OP, 1955 mpfr_rnd_t RND) 1956 Set simultaneously SOP to the hyperbolic sine of OP and COP to the 1957 hyperbolic cosine of OP, rounded in the direction RND with the 1958 corresponding precision of SOP and COP, which must be different 1959 variables. Return 0 iff both results are exact (see ‘mpfr_sin_cos’ 1960 for a more detailed description of the return value). 1961 1962 -- Function: int mpfr_sech (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1963 -- Function: int mpfr_csch (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1964 -- Function: int mpfr_coth (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1965 Set ROP to the hyperbolic secant of OP, cosecant of OP, cotangent 1966 of OP, rounded in the direction RND. 1967 1968 -- Function: int mpfr_acosh (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1969 -- Function: int mpfr_asinh (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1970 -- Function: int mpfr_atanh (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1971 Set ROP to the inverse hyperbolic cosine, sine or tangent of OP, 1972 rounded in the direction RND. 1973 1974 -- Function: int mpfr_eint (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1975 Set ROP to the exponential integral of OP, rounded in the direction 1976 RND. This is the sum of Euler’s constant, of the logarithm of the 1977 absolute value of OP, and of the sum for k from 1 to infinity of OP 1978 to the power k, divided by k and factorial(k). For positive OP, it 1979 corresponds to the Ei function at OP (see formula 5.1.10 from the 1980 Handbook of Mathematical Functions from Abramowitz and Stegun), and 1981 for negative OP, to the opposite of the E1 function (sometimes 1982 called eint1) at −OP (formula 5.1.1 from the same reference). 1983 1984 -- Function: int mpfr_li2 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1985 Set ROP to real part of the dilogarithm of OP, rounded in the 1986 direction RND. MPFR defines the dilogarithm function as the 1987 integral of -log(1-t)/t from 0 to OP. 1988 1989 -- Function: int mpfr_gamma (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 1990 -- Function: int mpfr_gamma_inc (mpfr_t ROP, mpfr_t OP, mpfr_t OP2, 1991 mpfr_rnd_t RND) 1992 Set ROP to the value of the Gamma function on OP, resp. the 1993 incomplete Gamma function on OP and OP2, rounded in the direction 1994 RND. (In the literature, ‘mpfr_gamma_inc’ is called upper 1995 incomplete Gamma function, or sometimes complementary incomplete 1996 Gamma function.) For ‘mpfr_gamma’ (and ‘mpfr_gamma_inc’ when OP2 1997 is zero), when OP is a negative integer, ROP is set to NaN. 1998 1999 Note: the current implementation of ‘mpfr_gamma_inc’ is slow for 2000 large values of ROP or OP, in which case some internal overflow 2001 might also occur. 2002 2003 -- Function: int mpfr_lngamma (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 2004 Set ROP to the value of the logarithm of the Gamma function on OP, 2005 rounded in the direction RND. When OP is 1 or 2, set ROP to +0 (in 2006 all rounding modes). When OP is an infinity or a nonpositive 2007 integer, set ROP to +Inf, following the general rules on special 2008 values. When −2K−1 < OP < −2K, K being a nonnegative integer, set 2009 ROP to NaN. See also ‘mpfr_lgamma’. 2010 2011 -- Function: int mpfr_lgamma (mpfr_t ROP, int *SIGNP, mpfr_t OP, 2012 mpfr_rnd_t RND) 2013 Set ROP to the value of the logarithm of the absolute value of the 2014 Gamma function on OP, rounded in the direction RND. The sign (1 or 2015 −1) of Gamma(OP) is returned in the object pointed to by SIGNP. 2016 When OP is 1 or 2, set ROP to +0 (in all rounding modes). When OP 2017 is an infinity or a nonpositive integer, set ROP to +Inf. When OP 2018 is NaN, −Inf or a negative integer, *SIGNP is undefined, and when 2019 OP is ±0, *SIGNP is the sign of the zero. 2020 2021 -- Function: int mpfr_digamma (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 2022 Set ROP to the value of the Digamma (sometimes also called Psi) 2023 function on OP, rounded in the direction RND. When OP is a 2024 negative integer, set ROP to NaN. 2025 2026 -- Function: int mpfr_beta (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, 2027 mpfr_rnd_t RND) 2028 Set ROP to the value of the Beta function at arguments OP1 and OP2. 2029 Note: the current code does not try to avoid internal overflow or 2030 underflow, and might use a huge internal precision in some cases. 2031 2032 -- Function: int mpfr_zeta (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 2033 -- Function: int mpfr_zeta_ui (mpfr_t ROP, unsigned long OP, mpfr_rnd_t 2034 RND) 2035 Set ROP to the value of the Riemann Zeta function on OP, rounded in 2036 the direction RND. 2037 2038 -- Function: int mpfr_erf (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 2039 -- Function: int mpfr_erfc (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 2040 Set ROP to the value of the error function on OP (resp. the 2041 complementary error function on OP) rounded in the direction RND. 2042 2043 -- Function: int mpfr_j0 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 2044 -- Function: int mpfr_j1 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 2045 -- Function: int mpfr_jn (mpfr_t ROP, long N, mpfr_t OP, mpfr_rnd_t 2046 RND) 2047 Set ROP to the value of the first kind Bessel function of order 0, 2048 (resp. 1 and N) on OP, rounded in the direction RND. When OP is 2049 NaN, ROP is always set to NaN. When OP is plus or minus Infinity, 2050 ROP is set to +0. When OP is zero, and N is not zero, ROP is set 2051 to +0 or −0 depending on the parity and sign of N, and the sign of 2052 OP. 2053 2054 -- Function: int mpfr_y0 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 2055 -- Function: int mpfr_y1 (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 2056 -- Function: int mpfr_yn (mpfr_t ROP, long N, mpfr_t OP, mpfr_rnd_t 2057 RND) 2058 Set ROP to the value of the second kind Bessel function of order 0 2059 (resp. 1 and N) on OP, rounded in the direction RND. When OP is 2060 NaN or negative, ROP is always set to NaN. When OP is +Inf, ROP is 2061 set to +0. When OP is zero, ROP is set to +Inf or −Inf depending 2062 on the parity and sign of N. 2063 2064 -- Function: int mpfr_agm (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, 2065 mpfr_rnd_t RND) 2066 Set ROP to the arithmetic-geometric mean of OP1 and OP2, rounded in 2067 the direction RND. The arithmetic-geometric mean is the common 2068 limit of the sequences U_N and V_N, where U_0=OP1, V_0=OP2, U_(N+1) 2069 is the arithmetic mean of U_N and V_N, and V_(N+1) is the geometric 2070 mean of U_N and V_N. If any operand is negative and the other one 2071 is not zero, set ROP to NaN. If any operand is zero and the other 2072 one is finite (resp. infinite), set ROP to +0 (resp. NaN). 2073 2074 -- Function: int mpfr_ai (mpfr_t ROP, mpfr_t X, mpfr_rnd_t RND) 2075 Set ROP to the value of the Airy function Ai on X, rounded in the 2076 direction RND. When X is NaN, ROP is always set to NaN. When X is 2077 +Inf or −Inf, ROP is +0. The current implementation is not 2078 intended to be used with large arguments. It works with abs(X) 2079 typically smaller than 500. For larger arguments, other methods 2080 should be used and will be implemented in a future version. 2081 2082 -- Function: int mpfr_const_log2 (mpfr_t ROP, mpfr_rnd_t RND) 2083 -- Function: int mpfr_const_pi (mpfr_t ROP, mpfr_rnd_t RND) 2084 -- Function: int mpfr_const_euler (mpfr_t ROP, mpfr_rnd_t RND) 2085 -- Function: int mpfr_const_catalan (mpfr_t ROP, mpfr_rnd_t RND) 2086 Set ROP to the logarithm of 2, the value of Pi, of Euler’s constant 2087 0.577..., of Catalan’s constant 0.915..., respectively, rounded in 2088 the direction RND. These functions cache the computed values to 2089 avoid other calculations if a lower or equal precision is 2090 requested. To free these caches, use ‘mpfr_free_cache’ or 2091 ‘mpfr_free_cache2’. 2092 2093 2094File: mpfr.info, Node: Input and Output Functions, Next: Formatted Output Functions, Prev: Transcendental Functions, Up: MPFR Interface 2095 20965.8 Input and Output Functions 2097============================== 2098 2099This section describes functions that perform input from an input/output 2100stream, and functions that output to an input/output stream. Passing a 2101null pointer for a ‘stream’ to any of these functions will make them 2102read from ‘stdin’ and write to ‘stdout’, respectively. 2103 2104 When using a function that takes a ‘FILE *’ argument, you must 2105include the ‘<stdio.h>’ standard header before ‘mpfr.h’, to allow 2106‘mpfr.h’ to define prototypes for these functions. 2107 2108 -- Function: size_t mpfr_out_str (FILE *STREAM, int BASE, size_t N, 2109 mpfr_t OP, mpfr_rnd_t RND) 2110 Output OP on stream STREAM as a text string in base abs(BASE), 2111 rounded in the direction RND. The base may vary from 2 to 62 or 2112 from −2 to −36 (any other value yields undefined behavior). The 2113 argument N has the same meaning as in ‘mpfr_get_str’ (*note 2114 mpfr_get_str::): Print N significant digits exactly, or if N is 0, 2115 the number ‘mpfr_get_str_ndigits(BASE,P)’ where P is the precision 2116 of OP (*note mpfr_get_str_ndigits::). 2117 2118 If the input is NaN, +Inf, −Inf, +0, or −0, then ‘@NaN@’, ‘@Inf@’, 2119 ‘-@Inf@’, ‘0’, or ‘-0’ is output, respectively. 2120 2121 For the regular numbers, the format of the output is the following: 2122 the most significant digit, then a decimal-point character (defined 2123 by the current locale), then the remaining N−1 digits (including 2124 trailing zeros), then the exponent prefix, then the exponent in 2125 decimal. The exponent prefix is ‘e’ when abs(BASE) <= 10, and ‘@’ 2126 when abs(BASE) > 10. *Note mpfr_get_str:: for information on the 2127 digits depending on the base. 2128 2129 Return the number of characters written, or if an error occurred, 2130 return 0. 2131 2132 -- Function: size_t mpfr_inp_str (mpfr_t ROP, FILE *STREAM, int BASE, 2133 mpfr_rnd_t RND) 2134 Input a string in base BASE from stream STREAM, rounded in the 2135 direction RND, and put the read float in ROP. 2136 2137 This function reads a word (defined as a sequence of characters 2138 between whitespace) and parses it using ‘mpfr_set_str’. See the 2139 documentation of ‘mpfr_strtofr’ for a detailed description of the 2140 valid string formats. 2141 2142 Return the number of bytes read, or if an error occurred, return 0. 2143 2144 -- Function: int mpfr_fpif_export (FILE *STREAM, mpfr_t OP) 2145 Export the number OP to the stream STREAM in a floating-point 2146 interchange format. In particular one can export on a 32-bit 2147 computer and import on a 64-bit computer, or export on a 2148 little-endian computer and import on a big-endian computer. The 2149 precision of OP and the sign bit of a NaN are stored too. Return 0 2150 iff the export was successful. 2151 2152 Note: this function is experimental and its interface might change 2153 in future versions. 2154 2155 -- Function: int mpfr_fpif_import (mpfr_t OP, FILE *STREAM) 2156 Import the number OP from the stream STREAM in a floating-point 2157 interchange format (see ‘mpfr_fpif_export’). Note that the 2158 precision of OP is set to the one read from the stream, and the 2159 sign bit is always retrieved (even for NaN). If the stored 2160 precision is zero or greater than ‘MPFR_PREC_MAX’, the function 2161 fails (it returns non-zero) and OP is unchanged. If the function 2162 fails for another reason, OP is set to NaN and it is unspecified 2163 whether the precision of OP has changed to the one read from the 2164 file. Return 0 iff the import was successful. 2165 2166 Note: this function is experimental and its interface might change 2167 in future versions. 2168 2169 -- Function: void mpfr_dump (mpfr_t OP) 2170 Output OP on ‘stdout’ in some unspecified format, then a newline 2171 character. This function is mainly for debugging purpose. Thus 2172 invalid data may be supported. Everything that is not specified 2173 may change without breaking the ABI and may depend on the 2174 environment. 2175 2176 The current output format is the following: a minus sign if the 2177 sign bit is set (even for NaN); ‘@NaN@’, ‘@Inf@’ or ‘0’ if the 2178 argument is NaN, an infinity or zero, respectively; otherwise the 2179 remaining of the output is as follows: ‘0.’ then the P bits of the 2180 binary significand, where P is the precision of the number; if the 2181 trailing bits are not all zeros (which must not occur with valid 2182 data), they are output enclosed by square brackets; the character 2183 ‘E’ followed by the exponent written in base 10; in case of invalid 2184 data or out-of-range exponent, this function outputs three 2185 exclamation marks (‘!!!’), followed by flags, followed by three 2186 exclamation marks (‘!!!’) again. These flags are: ‘N’ if the most 2187 significant bit of the significand is 0 (i.e., the number is not 2188 normalized); ‘T’ if there are non-zero trailing bits; ‘U’ if this 2189 is an UBF number (internal use only); ‘<’ if the exponent is less 2190 than the current minimum exponent; ‘>’ if the exponent is greater 2191 than the current maximum exponent. 2192 2193 2194File: mpfr.info, Node: Formatted Output Functions, Next: Integer and Remainder Related Functions, Prev: Input and Output Functions, Up: MPFR Interface 2195 21965.9 Formatted Output Functions 2197============================== 2198 21995.9.1 Requirements 2200------------------ 2201 2202The class of ‘mpfr_printf’ functions provides formatted output in a 2203similar manner as the standard C ‘printf’. These functions are defined 2204only if your system supports ISO C variadic functions and the 2205corresponding argument access macros. 2206 2207 When using any of these functions, you must include the ‘<stdio.h>’ 2208standard header before ‘mpfr.h’, to allow ‘mpfr.h’ to define prototypes 2209for these functions. 2210 22115.9.2 Format String 2212------------------- 2213 2214The format specification accepted by ‘mpfr_printf’ is an extension of 2215the ‘printf’ one. The conversion specification is of the form: 2216 % [flags] [width] [.[precision]] [type] [rounding] conv 2217 ‘flags’, ‘width’, and ‘precision’ have the same meaning as for the 2218standard ‘printf’ (in particular, notice that the ‘precision’ is related 2219to the number of digits displayed in the base chosen by ‘conv’ and not 2220related to the internal precision of the ‘mpfr_t’ variable), but note 2221that for ‘Re’, the default precision is not the same as the one for ‘e’. 2222‘mpfr_printf’ accepts the same ‘type’ specifiers as GMP (except the 2223non-standard and deprecated ‘q’, use ‘ll’ instead), namely the length 2224modifiers defined in the C standard: 2225 2226 ‘h’ ‘short’ 2227 ‘hh’ ‘char’ 2228 ‘j’ ‘intmax_t’ or ‘uintmax_t’ 2229 ‘l’ ‘long’ or ‘wchar_t’ 2230 ‘ll’ ‘long long’ 2231 ‘L’ ‘long double’ 2232 ‘t’ ‘ptrdiff_t’ 2233 ‘z’ ‘size_t’ 2234 2235 and the ‘type’ specifiers defined in GMP plus ‘R’ and ‘P’ specific to 2236MPFR (the second column in the table below shows the type of the 2237argument read in the argument list and the kind of ‘conv’ specifier to 2238use after the ‘type’ specifier): 2239 2240 ‘F’ ‘mpf_t’, float conversions 2241 ‘Q’ ‘mpq_t’, integer conversions 2242 ‘M’ ‘mp_limb_t’, integer conversions 2243 ‘N’ ‘mp_limb_t’ array, integer conversions 2244 ‘Z’ ‘mpz_t’, integer conversions 2245 2246 ‘P’ ‘mpfr_prec_t’, integer conversions 2247 ‘R’ ‘mpfr_t’, float conversions 2248 2249 The ‘type’ specifiers have the same restrictions as those mentioned 2250in the GMP documentation: *note (gmp.info)Formatted Output Strings::. 2251In particular, the ‘type’ specifiers (except ‘R’ and ‘P’) are supported 2252only if they are supported by ‘gmp_printf’ in your GMP build; this 2253implies that the standard specifiers, such as ‘t’, must _also_ be 2254supported by your C library if you want to use them. 2255 2256 The ‘rounding’ field is specific to ‘mpfr_t’ arguments and should not 2257be used with other types. 2258 2259 With conversion specification not involving ‘P’ and ‘R’ types, 2260‘mpfr_printf’ behaves exactly as ‘gmp_printf’. 2261 2262 The ‘P’ type specifies that a following ‘d’, ‘i’, ‘o’, ‘u’, ‘x’, or 2263‘X’ conversion specifier applies to a ‘mpfr_prec_t’ argument. It is 2264needed because the ‘mpfr_prec_t’ type does not necessarily correspond to 2265an ‘int’ or any fixed standard type. The ‘precision’ field specifies 2266the minimum number of digits to appear. The default ‘precision’ is 1. 2267For example: 2268 mpfr_t x; 2269 mpfr_prec_t p; 2270 mpfr_init (x); 2271 ... 2272 p = mpfr_get_prec (x); 2273 mpfr_printf ("variable x with %Pu bits", p); 2274 2275 The ‘R’ type specifies that a following ‘a’, ‘A’, ‘b’, ‘e’, ‘E’, ‘f’, 2276‘F’, ‘g’, ‘G’, or ‘n’ conversion specifier applies to a ‘mpfr_t’ 2277argument. The ‘R’ type can be followed by a ‘rounding’ specifier 2278denoted by one of the following characters: 2279 2280 ‘U’ round toward plus infinity 2281 ‘D’ round toward minus infinity 2282 ‘Y’ round away from zero 2283 ‘Z’ round toward zero 2284 ‘N’ round to nearest (with ties to even) 2285 ‘*’ rounding mode indicated by the 2286 ‘mpfr_rnd_t’ argument just before the 2287 corresponding ‘mpfr_t’ variable. 2288 2289 The default rounding mode is rounding to nearest. The following 2290three examples are equivalent: 2291 mpfr_t x; 2292 mpfr_init (x); 2293 ... 2294 mpfr_printf ("%.128Rf", x); 2295 mpfr_printf ("%.128RNf", x); 2296 mpfr_printf ("%.128R*f", MPFR_RNDN, x); 2297 2298 Note that the rounding away from zero mode is specified with ‘Y’ 2299because ISO C reserves the ‘A’ specifier for hexadecimal output (see 2300below). 2301 2302 The output ‘conv’ specifiers allowed with ‘mpfr_t’ parameter are: 2303 2304 ‘a’ ‘A’ hex float, C99 style 2305 ‘b’ binary output 2306 ‘e’ ‘E’ scientific-format float 2307 ‘f’ ‘F’ fixed-point float 2308 ‘g’ ‘G’ fixed-point or scientific float 2309 2310 The conversion specifier ‘b’ which displays the argument in binary is 2311specific to ‘mpfr_t’ arguments and should not be used with other types. 2312Other conversion specifiers have the same meaning as for a ‘double’ 2313argument. 2314 2315 In case of non-decimal output, only the significand is written in the 2316specified base, the exponent is always displayed in decimal. Special 2317values are always displayed as ‘nan’, ‘-inf’, and ‘inf’ for ‘a’, ‘b’, 2318‘e’, ‘f’, and ‘g’ specifiers and ‘NAN’, ‘-INF’, and ‘INF’ for ‘A’, ‘E’, 2319‘F’, and ‘G’ specifiers. 2320 2321 The ‘mpfr_t’ number is rounded to the given precision in the 2322direction specified by the rounding mode (see below if the ‘precision’ 2323field is empty). If the precision is zero with rounding to nearest mode 2324and one of the following ‘conv’ specifiers: ‘a’, ‘A’, ‘b’, ‘e’, ‘E’, tie 2325case is rounded to even when it lies between two consecutive values at 2326the wanted precision which have the same exponent, otherwise, it is 2327rounded away from zero. For instance, 85 is displayed as "8e+1" and 95 2328is displayed as "1e+2" with the format specification ‘"%.0RNe"’. This 2329also applies when the ‘g’ (resp. ‘G’) conversion specifier uses the ‘e’ 2330(resp. ‘E’) style. If the precision is set to a value greater than the 2331maximum value for an ‘int’, it will be silently reduced down to 2332‘INT_MAX’. 2333 2334 If the ‘precision’ field is empty with ‘conv’ specifier ‘e’ and ‘E’ 2335(as in ‘%Re’ or ‘%.RE’), the chosen precision (i.e., the number of 2336digits to be displayed after the initial digit and the decimal point) is 2337ceil(P*log(2)/log(10)), where P is the precision of the input variable, 2338matching the choice done for ‘mpfr_get_str’; thus, if rounding to 2339nearest is used, outputting the value with an empty ‘precision’ field 2340and reading it back will yield the original value. The chosen precision 2341for an empty ‘precision’ field with ‘conv’ specifiers ‘f’, ‘F’, ‘g’, and 2342‘G’ is 6. 2343 23445.9.3 Functions 2345--------------- 2346 2347For all the following functions, if the number of characters that ought 2348to be written exceeds the maximum limit ‘INT_MAX’ for an ‘int’, nothing 2349is written in the stream (resp. to ‘stdout’, to BUF, to STR), the 2350function returns −1, sets the _erange_ flag, and ‘errno’ is set to 2351‘EOVERFLOW’ if the ‘EOVERFLOW’ macro is defined (such as on POSIX 2352systems). Note, however, that ‘errno’ might be changed to another value 2353by some internal library call if another error occurs there (currently, 2354this would come from the unallocation function). 2355 2356 -- Function: int mpfr_fprintf (FILE *STREAM, const char *TEMPLATE, ...) 2357 -- Function: int mpfr_vfprintf (FILE *STREAM, const char *TEMPLATE, 2358 va_list AP) 2359 Print to the stream STREAM the optional arguments under the control 2360 of the template string TEMPLATE. Return the number of characters 2361 written or a negative value if an error occurred. 2362 2363 -- Function: int mpfr_printf (const char *TEMPLATE, ...) 2364 -- Function: int mpfr_vprintf (const char *TEMPLATE, va_list AP) 2365 Print to ‘stdout’ the optional arguments under the control of the 2366 template string TEMPLATE. Return the number of characters written 2367 or a negative value if an error occurred. 2368 2369 -- Function: int mpfr_sprintf (char *BUF, const char *TEMPLATE, ...) 2370 -- Function: int mpfr_vsprintf (char *BUF, const char *TEMPLATE, 2371 va_list AP) 2372 Form a null-terminated string corresponding to the optional 2373 arguments under the control of the template string TEMPLATE, and 2374 print it in BUF. No overlap is permitted between BUF and the other 2375 arguments. Return the number of characters written in the array 2376 BUF _not counting_ the terminating null character or a negative 2377 value if an error occurred. 2378 2379 -- Function: int mpfr_snprintf (char *BUF, size_t N, const char 2380 *TEMPLATE, ...) 2381 -- Function: int mpfr_vsnprintf (char *BUF, size_t N, const char 2382 *TEMPLATE, va_list AP) 2383 Form a null-terminated string corresponding to the optional 2384 arguments under the control of the template string TEMPLATE, and 2385 print it in BUF. If N is zero, nothing is written and BUF may be a 2386 null pointer, otherwise, the N−1 first characters are written in 2387 BUF and the N-th is a null character. Return the number of 2388 characters that would have been written had N been sufficiently 2389 large, _not counting_ the terminating null character, or a negative 2390 value if an error occurred. 2391 2392 -- Function: int mpfr_asprintf (char **STR, const char *TEMPLATE, ...) 2393 -- Function: int mpfr_vasprintf (char **STR, const char *TEMPLATE, 2394 va_list AP) 2395 Write their output as a null terminated string in a block of memory 2396 allocated using the allocation function (*note Memory Handling::). 2397 A pointer to the block is stored in STR. The block of memory must 2398 be freed using ‘mpfr_free_str’. The return value is the number of 2399 characters written in the string, excluding the null-terminator, or 2400 a negative value if an error occurred, in which case the contents 2401 of STR are undefined. 2402 2403 2404File: mpfr.info, Node: Integer and Remainder Related Functions, Next: Rounding-Related Functions, Prev: Formatted Output Functions, Up: MPFR Interface 2405 24065.10 Integer and Remainder Related Functions 2407============================================ 2408 2409 -- Function: int mpfr_rint (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 2410 -- Function: int mpfr_ceil (mpfr_t ROP, mpfr_t OP) 2411 -- Function: int mpfr_floor (mpfr_t ROP, mpfr_t OP) 2412 -- Function: int mpfr_round (mpfr_t ROP, mpfr_t OP) 2413 -- Function: int mpfr_roundeven (mpfr_t ROP, mpfr_t OP) 2414 -- Function: int mpfr_trunc (mpfr_t ROP, mpfr_t OP) 2415 Set ROP to OP rounded to an integer. ‘mpfr_rint’ rounds to the 2416 nearest representable integer in the given direction RND, and the 2417 other five functions behave in a similar way with some fixed 2418 rounding mode: 2419 • ‘mpfr_ceil’: to the next higher or equal representable integer 2420 (like ‘mpfr_rint’ with ‘MPFR_RNDU’); 2421 • ‘mpfr_floor’ to the next lower or equal representable integer 2422 (like ‘mpfr_rint’ with ‘MPFR_RNDD’); 2423 • ‘mpfr_round’ to the nearest representable integer, rounding 2424 halfway cases away from zero (as in the roundTiesToAway mode 2425 of IEEE 754-2008); 2426 • ‘mpfr_roundeven’ to the nearest representable integer, 2427 rounding halfway cases with the even-rounding rule (like 2428 ‘mpfr_rint’ with ‘MPFR_RNDN’); 2429 • ‘mpfr_trunc’ to the next representable integer toward zero 2430 (like ‘mpfr_rint’ with ‘MPFR_RNDZ’). 2431 When OP is a zero or an infinity, set ROP to the same value (with 2432 the same sign). 2433 2434 The return value is zero when the result is exact, positive when it 2435 is greater than the original value of OP, and negative when it is 2436 smaller. More precisely, the return value is 0 when OP is an 2437 integer representable in ROP, 1 or −1 when OP is an integer that is 2438 not representable in ROP, 2 or −2 when OP is not an integer. 2439 2440 When OP is NaN, the NaN flag is set as usual. In the other cases, 2441 the inexact flag is set when ROP differs from OP, following the ISO 2442 C99 rule for the ‘rint’ function. If you want the behavior to be 2443 more like IEEE 754 / ISO TS 18661-1, i.e., the usual behavior where 2444 the round-to-integer function is regarded as any other mathematical 2445 function, you should use one the ‘mpfr_rint_*’ functions instead. 2446 2447 Note that no double rounding is performed; for instance, 10.5 2448 (1010.1 in binary) is rounded by ‘mpfr_rint’ with rounding to 2449 nearest to 12 (1100 in binary) in 2-bit precision, because the two 2450 enclosing numbers representable on two bits are 8 and 12, and the 2451 closest is 12. (If one first rounded to an integer, one would 2452 round 10.5 to 10 with even rounding, and then 10 would be rounded 2453 to 8 again with even rounding.) 2454 2455 -- Function: int mpfr_rint_ceil (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 2456 -- Function: int mpfr_rint_floor (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t 2457 RND) 2458 -- Function: int mpfr_rint_round (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t 2459 RND) 2460 -- Function: int mpfr_rint_roundeven (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t 2461 RND) 2462 -- Function: int mpfr_rint_trunc (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t 2463 RND) 2464 Set ROP to OP rounded to an integer: 2465 • ‘mpfr_rint_ceil’: to the next higher or equal integer; 2466 • ‘mpfr_rint_floor’: to the next lower or equal integer; 2467 • ‘mpfr_rint_round’: to the nearest integer, rounding halfway 2468 cases away from zero; 2469 • ‘mpfr_rint_roundeven’: to the nearest integer, rounding 2470 halfway cases to the nearest even integer; 2471 • ‘mpfr_rint_trunc’ to the next integer toward zero. 2472 If the result is not representable, it is rounded in the direction 2473 RND. When OP is a zero or an infinity, set ROP to the same value 2474 (with the same sign). The return value is the ternary value 2475 associated with the considered round-to-integer function (regarded 2476 in the same way as any other mathematical function). 2477 2478 Contrary to ‘mpfr_rint’, those functions do perform a double 2479 rounding: first OP is rounded to the nearest integer in the 2480 direction given by the function name, then this nearest integer (if 2481 not representable) is rounded in the given direction RND. Thus 2482 these round-to-integer functions behave more like the other 2483 mathematical functions, i.e., the returned result is the correct 2484 rounding of the exact result of the function in the real numbers. 2485 2486 For example, ‘mpfr_rint_round’ with rounding to nearest and a 2487 precision of two bits rounds 6.5 to 7 (halfway cases away from 2488 zero), then 7 is rounded to 8 by the round-even rule, despite the 2489 fact that 6 is also representable on two bits, and is closer to 6.5 2490 than 8. 2491 2492 -- Function: int mpfr_frac (mpfr_t ROP, mpfr_t OP, mpfr_rnd_t RND) 2493 Set ROP to the fractional part of OP, having the same sign as OP, 2494 rounded in the direction RND (unlike in ‘mpfr_rint’, RND affects 2495 only how the exact fractional part is rounded, not how the 2496 fractional part is generated). When OP is an integer or an 2497 infinity, set ROP to zero with the same sign as OP. 2498 2499 -- Function: int mpfr_modf (mpfr_t IOP, mpfr_t FOP, mpfr_t OP, 2500 mpfr_rnd_t RND) 2501 Set simultaneously IOP to the integral part of OP and FOP to the 2502 fractional part of OP, rounded in the direction RND with the 2503 corresponding precision of IOP and FOP (equivalent to 2504 ‘mpfr_trunc(IOP, OP, RND)’ and ‘mpfr_frac(FOP, OP, RND)’). The 2505 variables IOP and FOP must be different. Return 0 iff both results 2506 are exact (see ‘mpfr_sin_cos’ for a more detailed description of 2507 the return value). 2508 2509 -- Function: int mpfr_fmod (mpfr_t R, mpfr_t X, mpfr_t Y, mpfr_rnd_t 2510 RND) 2511 -- Function: int mpfr_fmodquo (mpfr_t R, long* Q, mpfr_t X, mpfr_t Y, 2512 mpfr_rnd_t RND) 2513 -- Function: int mpfr_remainder (mpfr_t R, mpfr_t X, mpfr_t Y, 2514 mpfr_rnd_t RND) 2515 -- Function: int mpfr_remquo (mpfr_t R, long* Q, mpfr_t X, mpfr_t Y, 2516 mpfr_rnd_t RND) 2517 Set R to the value of X - NY, rounded according to the direction 2518 RND, where N is the integer quotient of X divided by Y, defined as 2519 follows: N is rounded toward zero for ‘mpfr_fmod’ and 2520 ‘mpfr_fmodquo’, and to the nearest integer (ties rounded to even) 2521 for ‘mpfr_remainder’ and ‘mpfr_remquo’. 2522 2523 Special values are handled as described in Section F.9.7.1 of the 2524 ISO C99 standard: If X is infinite or Y is zero, R is NaN. If Y is 2525 infinite and X is finite, R is X rounded to the precision of R. If 2526 R is zero, it has the sign of X. The return value is the ternary 2527 value corresponding to R. 2528 2529 Additionally, ‘mpfr_fmodquo’ and ‘mpfr_remquo’ store the low 2530 significant bits from the quotient N in *Q (more precisely the 2531 number of bits in a ‘long’ minus one), with the sign of X divided 2532 by Y (except if those low bits are all zero, in which case zero is 2533 returned). Note that X may be so large in magnitude relative to Y 2534 that an exact representation of the quotient is not practical. The 2535 ‘mpfr_remainder’ and ‘mpfr_remquo’ functions are useful for 2536 additive argument reduction. 2537 2538 -- Function: int mpfr_integer_p (mpfr_t OP) 2539 Return non-zero iff OP is an integer. 2540 2541 2542File: mpfr.info, Node: Rounding-Related Functions, Next: Miscellaneous Functions, Prev: Integer and Remainder Related Functions, Up: MPFR Interface 2543 25445.11 Rounding-Related Functions 2545=============================== 2546 2547 -- Function: void mpfr_set_default_rounding_mode (mpfr_rnd_t RND) 2548 Set the default rounding mode to RND. The default rounding mode is 2549 to nearest initially. 2550 2551 -- Function: mpfr_rnd_t mpfr_get_default_rounding_mode (void) 2552 Get the default rounding mode. 2553 2554 -- Function: int mpfr_prec_round (mpfr_t X, mpfr_prec_t PREC, 2555 mpfr_rnd_t RND) 2556 Round X according to RND with precision PREC, which must be an 2557 integer between ‘MPFR_PREC_MIN’ and ‘MPFR_PREC_MAX’ (otherwise the 2558 behavior is undefined). If PREC is greater than or equal to the 2559 precision of X, then new space is allocated for the significand, 2560 and it is filled with zeros. Otherwise, the significand is rounded 2561 to precision PREC with the given direction; no memory reallocation 2562 to free the unused limbs is done. In both cases, the precision of 2563 X is changed to PREC. 2564 2565 Here is an example of how to use ‘mpfr_prec_round’ to implement 2566 Newton’s algorithm to compute the inverse of A, assuming X is 2567 already an approximation to N bits: 2568 mpfr_set_prec (t, 2 * n); 2569 mpfr_set (t, a, MPFR_RNDN); /* round a to 2n bits */ 2570 mpfr_mul (t, t, x, MPFR_RNDN); /* t is correct to 2n bits */ 2571 mpfr_ui_sub (t, 1, t, MPFR_RNDN); /* high n bits cancel with 1 */ 2572 mpfr_prec_round (t, n, MPFR_RNDN); /* t is correct to n bits */ 2573 mpfr_mul (t, t, x, MPFR_RNDN); /* t is correct to n bits */ 2574 mpfr_prec_round (x, 2 * n, MPFR_RNDN); /* exact */ 2575 mpfr_add (x, x, t, MPFR_RNDN); /* x is correct to 2n bits */ 2576 2577 Warning! You must not use this function if X was initialized with 2578 ‘MPFR_DECL_INIT’ or with ‘mpfr_custom_init_set’ (*note Custom 2579 Interface::). 2580 2581 -- Function: int mpfr_can_round (mpfr_t B, mpfr_exp_t ERR, mpfr_rnd_t 2582 RND1, mpfr_rnd_t RND2, mpfr_prec_t PREC) 2583 Assuming B is an approximation of an unknown number X in the 2584 direction RND1 with error at most two to the power E(b)-ERR where 2585 E(b) is the exponent of B, return a non-zero value if one is able 2586 to round correctly X to precision PREC with the direction RND2 2587 assuming an unbounded exponent range, and 0 otherwise (including 2588 for NaN and Inf). In other words, if the error on B is bounded by 2589 two to the power K ulps, and B has precision PREC, you should give 2590 ERR=PREC−K. This function *does not modify* its arguments. 2591 2592 If RND1 is ‘MPFR_RNDN’ or ‘MPFR_RNDF’, the error is considered to 2593 be either positive or negative, thus the possible range is twice as 2594 large as with a directed rounding for RND1 (with the same value of 2595 ERR). 2596 2597 When RND2 is ‘MPFR_RNDF’, let RND3 be the opposite direction if 2598 RND1 is a directed rounding, and ‘MPFR_RNDN’ if RND1 is ‘MPFR_RNDN’ 2599 or ‘MPFR_RNDF’. The returned value of ‘mpfr_can_round (b, err, 2600 rnd1, MPFR_RNDF, prec)’ is non-zero iff after the call ‘mpfr_set 2601 (y, b, rnd3)’ with Y of precision PREC, Y is guaranteed to be a 2602 faithful rounding of X. 2603 2604 Note: The *note ternary value:: cannot be determined in general 2605 with this function. However, if it is known that the exact value 2606 is not exactly representable in precision PREC, then one can use 2607 the following trick to determine the (non-zero) ternary value in 2608 any rounding mode RND2 (note that ‘MPFR_RNDZ’ below can be replaced 2609 by any directed rounding mode): 2610 if (mpfr_can_round (b, err, MPFR_RNDN, MPFR_RNDZ, 2611 prec + (rnd2 == MPFR_RNDN))) 2612 { 2613 /* round the approximation 'b' to the result 'r' of 'prec' bits 2614 with rounding mode 'rnd2' and get the ternary value 'inex' */ 2615 inex = mpfr_set (r, b, rnd2); 2616 } 2617 Indeed, if RND2 is ‘MPFR_RNDN’, this will check if one can round to 2618 PREC+1 bits with a directed rounding: if so, one can surely round 2619 to nearest to PREC bits, and in addition one can determine the 2620 correct ternary value, which would not be the case when B is near 2621 from a value exactly representable on PREC bits. 2622 2623 A detailed example is available in the ‘examples’ subdirectory, 2624 file ‘can_round.c’. 2625 2626 -- Function: mpfr_prec_t mpfr_min_prec (mpfr_t X) 2627 Return the minimal number of bits required to store the significand 2628 of X, and 0 for special values, including 0. 2629 2630 -- Function: const char * mpfr_print_rnd_mode (mpfr_rnd_t RND) 2631 Return a string ("MPFR_RNDN", "MPFR_RNDZ", "MPFR_RNDU", 2632 "MPFR_RNDD", "MPFR_RNDA", "MPFR_RNDF") corresponding to the 2633 rounding mode RND, or a null pointer if RND is an invalid rounding 2634 mode. 2635 2636 -- Macro: int mpfr_round_nearest_away (int (FOO)(mpfr_t, type1_t, ..., 2637 mpfr_rnd_t), mpfr_t ROP, type1_t OP, ...) 2638 Given a function FOO and one or more values OP (which may be a 2639 ‘mpfr_t’, a ‘long’, a ‘double’, etc.), put in ROP the 2640 round-to-nearest-away rounding of ‘FOO(OP,...)’. This rounding is 2641 defined in the same way as round-to-nearest-even, except in case of 2642 tie, where the value away from zero is returned. The function FOO 2643 takes as input, from second to penultimate argument(s), the 2644 argument list given after ROP, a rounding mode as final argument, 2645 puts in its first argument the value ‘FOO(OP,...)’ rounded 2646 according to this rounding mode, and returns the corresponding 2647 ternary value (which is expected to be correct, otherwise 2648 ‘mpfr_round_nearest_away’ will not work as desired). Due to 2649 implementation constraints, this function must not be called when 2650 the minimal exponent ‘emin’ is the smallest possible one. This 2651 macro has been made such that the compiler is able to detect 2652 mismatch between the argument list OP and the function prototype of 2653 FOO. Multiple input arguments OP are supported only with C99 2654 compilers. Otherwise, for C89 compilers, only one such argument is 2655 supported. 2656 2657 Note: this macro is experimental and its interface might change in 2658 future versions. 2659 unsigned long ul; 2660 mpfr_t f, r; 2661 /* Code that inits and sets r, f, and ul, and if needed sets emin */ 2662 int i = mpfr_round_nearest_away (mpfr_add_ui, r, f, ul); 2663 2664 2665File: mpfr.info, Node: Miscellaneous Functions, Next: Exception Related Functions, Prev: Rounding-Related Functions, Up: MPFR Interface 2666 26675.12 Miscellaneous Functions 2668============================ 2669 2670 -- Function: void mpfr_nexttoward (mpfr_t X, mpfr_t Y) 2671 If X or Y is NaN, set X to NaN; note that the NaN flag is set as 2672 usual. If X and Y are equal, X is unchanged. Otherwise, if X is 2673 different from Y, replace X by the next floating-point number (with 2674 the precision of X and the current exponent range) in the direction 2675 of Y (the infinite values are seen as the smallest and largest 2676 floating-point numbers). If the result is zero, it keeps the same 2677 sign. No underflow, overflow, or inexact exception is raised. 2678 2679 -- Function: void mpfr_nextabove (mpfr_t X) 2680 -- Function: void mpfr_nextbelow (mpfr_t X) 2681 Equivalent to ‘mpfr_nexttoward’ where Y is plus infinity (resp. 2682 minus infinity). 2683 2684 -- Function: int mpfr_min (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, 2685 mpfr_rnd_t RND) 2686 -- Function: int mpfr_max (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, 2687 mpfr_rnd_t RND) 2688 Set ROP to the minimum (resp. maximum) of OP1 and OP2. If OP1 and 2689 OP2 are both NaN, then ROP is set to NaN. If OP1 or OP2 is NaN, 2690 then ROP is set to the numeric value. If OP1 and OP2 are zeros of 2691 different signs, then ROP is set to −0 (resp. +0). 2692 2693 -- Function: int mpfr_urandomb (mpfr_t ROP, gmp_randstate_t STATE) 2694 Generate a uniformly distributed random float in the interval 0 <= 2695 ROP < 1. More precisely, the number can be seen as a float with a 2696 random non-normalized significand and exponent 0, which is then 2697 normalized (thus if E denotes the exponent after normalization, 2698 then the least -E significant bits of the significand are always 2699 0). 2700 2701 Return 0, unless the exponent is not in the current exponent range, 2702 in which case ROP is set to NaN and a non-zero value is returned 2703 (this should never happen in practice, except in very specific 2704 cases). The second argument is a ‘gmp_randstate_t’ structure which 2705 should be created using the GMP ‘gmp_randinit’ function (see the 2706 GMP manual). 2707 2708 Note: for a given version of MPFR, the returned value of ROP and 2709 the new value of STATE (which controls further random values) do 2710 not depend on the machine word size. 2711 2712 -- Function: int mpfr_urandom (mpfr_t ROP, gmp_randstate_t STATE, 2713 mpfr_rnd_t RND) 2714 Generate a uniformly distributed random float. The floating-point 2715 number ROP can be seen as if a random real number is generated 2716 according to the continuous uniform distribution on the interval 2717 [0, 1] and then rounded in the direction RND. 2718 2719 The second argument is a ‘gmp_randstate_t’ structure which should 2720 be created using the GMP ‘gmp_randinit’ function (see the GMP 2721 manual). 2722 2723 Note: the note for ‘mpfr_urandomb’ holds too. Moreover, the exact 2724 number (the random value to be rounded) and the next random state 2725 do not depend on the current exponent range and the rounding mode. 2726 However, they depend on the target precision: from the same state 2727 of the random generator, if the precision of the destination is 2728 changed, then the value may be completely different (and the state 2729 of the random generator is different too). 2730 2731 -- Function: int mpfr_nrandom (mpfr_t ROP1, gmp_randstate_t STATE, 2732 mpfr_rnd_t RND) 2733 -- Function: int mpfr_grandom (mpfr_t ROP1, mpfr_t ROP2, 2734 gmp_randstate_t STATE, mpfr_rnd_t RND) 2735 Generate one (possibly two for ‘mpfr_grandom’) random 2736 floating-point number according to a standard normal Gaussian 2737 distribution (with mean zero and variance one). For 2738 ‘mpfr_grandom’, if ROP2 is a null pointer, then only one value is 2739 generated and stored in ROP1. 2740 2741 The floating-point number ROP1 (and ROP2) can be seen as if a 2742 random real number were generated according to the standard normal 2743 Gaussian distribution and then rounded in the direction RND. 2744 2745 The ‘gmp_randstate_t’ argument should be created using the GMP 2746 ‘gmp_randinit’ function (see the GMP manual). 2747 2748 For ‘mpfr_grandom’, the combination of the ternary values is 2749 returned like with ‘mpfr_sin_cos’. If ROP2 is a null pointer, the 2750 second ternary value is assumed to be 0 (note that the encoding of 2751 the only ternary value is not the same as the usual encoding for 2752 functions that return only one result). Otherwise the ternary 2753 value of a random number is always non-zero. 2754 2755 Note: the note for ‘mpfr_urandomb’ holds too. In addition, the 2756 exponent range and the rounding mode might have a side effect on 2757 the next random state. 2758 2759 Note: ‘mpfr_nrandom’ is much more efficient than ‘mpfr_grandom’, 2760 especially for large precision. Thus ‘mpfr_grandom’ is marked as 2761 deprecated and will be removed in a future release. 2762 2763 -- Function: int mpfr_erandom (mpfr_t ROP1, gmp_randstate_t STATE, 2764 mpfr_rnd_t RND) 2765 Generate one random floating-point number according to an 2766 exponential distribution, with mean one. Other characteristics are 2767 identical to ‘mpfr_nrandom’. 2768 2769 -- Function: mpfr_exp_t mpfr_get_exp (mpfr_t X) 2770 Return the exponent of X, assuming that X is a non-zero ordinary 2771 number and the significand is considered in [1/2,1). For this 2772 function, X is allowed to be outside of the current range of 2773 acceptable values. The behavior for NaN, infinity or zero is 2774 undefined. 2775 2776 -- Function: int mpfr_set_exp (mpfr_t X, mpfr_exp_t E) 2777 Set the exponent of X to E if X is a non-zero ordinary number and E 2778 is in the current exponent range, and return 0; otherwise, return a 2779 non-zero value (X is not changed). 2780 2781 -- Function: int mpfr_signbit (mpfr_t OP) 2782 Return a non-zero value iff OP has its sign bit set (i.e., if it is 2783 negative, −0, or a NaN whose representation has its sign bit set). 2784 2785 -- Function: int mpfr_setsign (mpfr_t ROP, mpfr_t OP, int S, mpfr_rnd_t 2786 RND) 2787 Set the value of ROP from OP, rounded toward the given direction 2788 RND, then set (resp. clear) its sign bit if S is non-zero (resp. 2789 zero), even when OP is a NaN. 2790 2791 -- Function: int mpfr_copysign (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, 2792 mpfr_rnd_t RND) 2793 Set the value of ROP from OP1, rounded toward the given direction 2794 RND, then set its sign bit to that of OP2 (even when OP1 or OP2 is 2795 a NaN). This function is equivalent to ‘mpfr_setsign (ROP, OP1, 2796 mpfr_signbit (OP2), RND)’. 2797 2798 -- Function: const char * mpfr_get_version (void) 2799 Return the MPFR version, as a null-terminated string. 2800 2801 -- Macro: MPFR_VERSION 2802 -- Macro: MPFR_VERSION_MAJOR 2803 -- Macro: MPFR_VERSION_MINOR 2804 -- Macro: MPFR_VERSION_PATCHLEVEL 2805 -- Macro: MPFR_VERSION_STRING 2806 ‘MPFR_VERSION’ is the version of MPFR as a preprocessing constant. 2807 ‘MPFR_VERSION_MAJOR’, ‘MPFR_VERSION_MINOR’ and 2808 ‘MPFR_VERSION_PATCHLEVEL’ are respectively the major, minor and 2809 patch level of MPFR version, as preprocessing constants. 2810 ‘MPFR_VERSION_STRING’ is the version (with an optional suffix, used 2811 in development and pre-release versions) as a string constant, 2812 which can be compared to the result of ‘mpfr_get_version’ to check 2813 at run time the header file and library used match: 2814 if (strcmp (mpfr_get_version (), MPFR_VERSION_STRING)) 2815 fprintf (stderr, "Warning: header and library do not match\n"); 2816 Note: Obtaining different strings is not necessarily an error, as 2817 in general, a program compiled with some old MPFR version can be 2818 dynamically linked with a newer MPFR library version (if allowed by 2819 the library versioning system). 2820 2821 -- Macro: long MPFR_VERSION_NUM (MAJOR, MINOR, PATCHLEVEL) 2822 Create an integer in the same format as used by ‘MPFR_VERSION’ from 2823 the given MAJOR, MINOR and PATCHLEVEL. Here is an example of how 2824 to check the MPFR version at compile time: 2825 #if (!defined(MPFR_VERSION) || (MPFR_VERSION<MPFR_VERSION_NUM(3,0,0))) 2826 # error "Wrong MPFR version." 2827 #endif 2828 2829 -- Function: const char * mpfr_get_patches (void) 2830 Return a null-terminated string containing the ids of the patches 2831 applied to the MPFR library (contents of the ‘PATCHES’ file), 2832 separated by spaces. Note: If the program has been compiled with 2833 an older MPFR version and is dynamically linked with a new MPFR 2834 library version, the identifiers of the patches applied to the old 2835 (compile-time) MPFR version are not available (however this 2836 information should not have much interest in general). 2837 2838 -- Function: int mpfr_buildopt_tls_p (void) 2839 Return a non-zero value if MPFR was compiled as thread safe using 2840 compiler-level Thread-Local Storage (that is, MPFR was built with 2841 the ‘--enable-thread-safe’ configure option, see ‘INSTALL’ file), 2842 return zero otherwise. 2843 2844 -- Function: int mpfr_buildopt_float128_p (void) 2845 Return a non-zero value if MPFR was compiled with ‘_Float128’ 2846 support (that is, MPFR was built with the ‘--enable-float128’ 2847 configure option), return zero otherwise. 2848 2849 -- Function: int mpfr_buildopt_decimal_p (void) 2850 Return a non-zero value if MPFR was compiled with decimal float 2851 support (that is, MPFR was built with the ‘--enable-decimal-float’ 2852 configure option), return zero otherwise. 2853 2854 -- Function: int mpfr_buildopt_gmpinternals_p (void) 2855 Return a non-zero value if MPFR was compiled with GMP internals 2856 (that is, MPFR was built with either ‘--with-gmp-build’ or 2857 ‘--enable-gmp-internals’ configure option), return zero otherwise. 2858 2859 -- Function: int mpfr_buildopt_sharedcache_p (void) 2860 Return a non-zero value if MPFR was compiled so that all threads 2861 share the same cache for one MPFR constant, like ‘mpfr_const_pi’ or 2862 ‘mpfr_const_log2’ (that is, MPFR was built with the 2863 ‘--enable-shared-cache’ configure option), return zero otherwise. 2864 If the return value is non-zero, MPFR applications may need to be 2865 compiled with the ‘-pthread’ option. 2866 2867 -- Function: const char * mpfr_buildopt_tune_case (void) 2868 Return a string saying which thresholds file has been used at 2869 compile time. This file is normally selected from the processor 2870 type. 2871 2872 2873File: mpfr.info, Node: Exception Related Functions, Next: Memory Handling Functions, Prev: Miscellaneous Functions, Up: MPFR Interface 2874 28755.13 Exception Related Functions 2876================================ 2877 2878 -- Function: mpfr_exp_t mpfr_get_emin (void) 2879 -- Function: mpfr_exp_t mpfr_get_emax (void) 2880 Return the (current) smallest and largest exponents allowed for a 2881 floating-point variable. The smallest positive value of a 2882 floating-point variable is one half times 2 raised to the smallest 2883 exponent and the largest value has the form (1 - epsilon) times 2 2884 raised to the largest exponent, where epsilon depends on the 2885 precision of the considered variable. 2886 2887 -- Function: int mpfr_set_emin (mpfr_exp_t EXP) 2888 -- Function: int mpfr_set_emax (mpfr_exp_t EXP) 2889 Set the smallest and largest exponents allowed for a floating-point 2890 variable. Return a non-zero value when EXP is not in the range 2891 accepted by the implementation (in that case the smallest or 2892 largest exponent is not changed), and zero otherwise. 2893 2894 For the subsequent operations, it is the user’s responsibility to 2895 check that any floating-point value used as an input is in the new 2896 exponent range (for example using ‘mpfr_check_range’). If a 2897 floating-point value outside the new exponent range is used as an 2898 input, the default behavior is undefined, in the sense of the ISO C 2899 standard; the behavior may also be explicitly documented, such as 2900 for ‘mpfr_check_range’. 2901 2902 Note: Caches may still have values outside the current exponent 2903 range. This is not an issue as the user cannot use these caches 2904 directly via the API (MPFR extends the exponent range internally 2905 when need be). 2906 2907 If ‘emin’ > ‘emax’ and a floating-point value needs to be produced 2908 as output, the behavior is undefined (‘mpfr_set_emin’ and 2909 ‘mpfr_set_emax’ do not check this condition as it might occur 2910 between successive calls to these two functions). 2911 2912 -- Function: mpfr_exp_t mpfr_get_emin_min (void) 2913 -- Function: mpfr_exp_t mpfr_get_emin_max (void) 2914 -- Function: mpfr_exp_t mpfr_get_emax_min (void) 2915 -- Function: mpfr_exp_t mpfr_get_emax_max (void) 2916 Return the minimum and maximum of the exponents allowed for 2917 ‘mpfr_set_emin’ and ‘mpfr_set_emax’ respectively. These values are 2918 implementation dependent, thus a program using 2919 ‘mpfr_set_emax(mpfr_get_emax_max())’ or 2920 ‘mpfr_set_emin(mpfr_get_emin_min())’ may not be portable. 2921 2922 -- Function: int mpfr_check_range (mpfr_t X, int T, mpfr_rnd_t RND) 2923 This function assumes that X is the correctly rounded value of some 2924 real value Y in the direction RND and some extended exponent range, 2925 and that T is the corresponding *note ternary value::. For 2926 example, one performed ‘t = mpfr_log (x, u, rnd)’, and Y is the 2927 exact logarithm of U. Thus T is negative if X is smaller than Y, 2928 positive if X is larger than Y, and zero if X equals Y. This 2929 function modifies X if needed to be in the current range of 2930 acceptable values: It generates an underflow or an overflow if the 2931 exponent of X is outside the current allowed range; the value of T 2932 may be used to avoid a double rounding. This function returns zero 2933 if the new value of X equals the exact one Y, a positive value if 2934 that new value is larger than Y, and a negative value if it is 2935 smaller than Y. Note that unlike most functions, the new result X 2936 is compared to the (unknown) exact one Y, not the input value X, 2937 i.e., the ternary value is propagated. 2938 2939 Note: If X is an infinity and T is different from zero (i.e., if 2940 the rounded result is an inexact infinity), then the overflow flag 2941 is set. This is useful because ‘mpfr_check_range’ is typically 2942 called (at least in MPFR functions) after restoring the flags that 2943 could have been set due to internal computations. 2944 2945 -- Function: int mpfr_subnormalize (mpfr_t X, int T, mpfr_rnd_t RND) 2946 This function rounds X emulating subnormal number arithmetic: if X 2947 is outside the subnormal exponent range of the emulated 2948 floating-point system, this function just propagates the *note 2949 ternary value:: T; otherwise, it rounds X to precision 2950 ‘EXP(X)-emin+1’ according to rounding mode RND and previous ternary 2951 value T, avoiding double rounding problems. More precisely in the 2952 subnormal domain, denoting by E the value of ‘emin’, X is rounded 2953 in fixed-point arithmetic to an integer multiple of two to the 2954 power E−1; as a consequence, 1.5 multiplied by two to the power E−1 2955 when T is zero is rounded to two to the power E with rounding to 2956 nearest. 2957 2958 ‘PREC(X)’ is not modified by this function. RND and T must be the 2959 rounding mode and the returned ternary value used when computing X 2960 (as in ‘mpfr_check_range’). The subnormal exponent range is from 2961 ‘emin’ to ‘emin+PREC(X)-1’. If the result cannot be represented in 2962 the current exponent range of MPFR (due to a too small ‘emax’), the 2963 behavior is undefined. Note that unlike most functions, the result 2964 is compared to the exact one, not the input value X, i.e., the 2965 ternary value is propagated. 2966 2967 As usual, if the returned ternary value is non zero, the inexact 2968 flag is set. Moreover, if a second rounding occurred (because the 2969 input X was in the subnormal range), the underflow flag is set. 2970 2971 Warning! If you change ‘emin’ (with ‘mpfr_set_emin’) just before 2972 calling ‘mpfr_subnormalize’, you need to make sure that the value 2973 is in the current exponent range of MPFR. But it is better to 2974 change ‘emin’ before any computation, if possible. 2975 2976 This is an example of how to emulate binary double IEEE 754 2977arithmetic (binary64 in IEEE 754-2008) using MPFR: 2978 2979 { 2980 mpfr_t xa, xb; int i; volatile double a, b; 2981 2982 mpfr_set_default_prec (53); 2983 mpfr_set_emin (-1073); mpfr_set_emax (1024); 2984 2985 mpfr_init (xa); mpfr_init (xb); 2986 2987 b = 34.3; mpfr_set_d (xb, b, MPFR_RNDN); 2988 a = 0x1.1235P-1021; mpfr_set_d (xa, a, MPFR_RNDN); 2989 2990 a /= b; 2991 i = mpfr_div (xa, xa, xb, MPFR_RNDN); 2992 i = mpfr_subnormalize (xa, i, MPFR_RNDN); /* new ternary value */ 2993 2994 mpfr_clear (xa); mpfr_clear (xb); 2995 } 2996 2997 Note that ‘mpfr_set_emin’ and ‘mpfr_set_emax’ are called early enough 2998in order to make sure that all computed values are in the current 2999exponent range. Warning! This emulates a double IEEE 754 arithmetic 3000with correct rounding in the subnormal range, which may not be the case 3001for your hardware. 3002 3003 Below is another example showing how to emulate fixed-point 3004arithmetic in a specific case. Here we compute the sine of the integers 30051 to 17 with a result in a fixed-point arithmetic rounded at 2 power -42 3006(using the fact that the result is at most 1 in absolute value): 3007 3008 { 3009 mpfr_t x; int i, inex; 3010 3011 mpfr_set_emin (-41); 3012 mpfr_init2 (x, 42); 3013 for (i = 1; i <= 17; i++) 3014 { 3015 mpfr_set_ui (x, i, MPFR_RNDN); 3016 inex = mpfr_sin (x, x, MPFR_RNDZ); 3017 mpfr_subnormalize (x, inex, MPFR_RNDZ); 3018 mpfr_dump (x); 3019 } 3020 mpfr_clear (x); 3021 } 3022 3023 -- Function: void mpfr_clear_underflow (void) 3024 -- Function: void mpfr_clear_overflow (void) 3025 -- Function: void mpfr_clear_divby0 (void) 3026 -- Function: void mpfr_clear_nanflag (void) 3027 -- Function: void mpfr_clear_inexflag (void) 3028 -- Function: void mpfr_clear_erangeflag (void) 3029 Clear (lower) the underflow, overflow, divide-by-zero, invalid, 3030 inexact and _erange_ flags. 3031 3032 -- Function: void mpfr_clear_flags (void) 3033 Clear (lower) all global flags (underflow, overflow, 3034 divide-by-zero, invalid, inexact, _erange_). Note: a group of 3035 flags can be cleared by using ‘mpfr_flags_clear’. 3036 3037 -- Function: void mpfr_set_underflow (void) 3038 -- Function: void mpfr_set_overflow (void) 3039 -- Function: void mpfr_set_divby0 (void) 3040 -- Function: void mpfr_set_nanflag (void) 3041 -- Function: void mpfr_set_inexflag (void) 3042 -- Function: void mpfr_set_erangeflag (void) 3043 Set (raise) the underflow, overflow, divide-by-zero, invalid, 3044 inexact and _erange_ flags. 3045 3046 -- Function: int mpfr_underflow_p (void) 3047 -- Function: int mpfr_overflow_p (void) 3048 -- Function: int mpfr_divby0_p (void) 3049 -- Function: int mpfr_nanflag_p (void) 3050 -- Function: int mpfr_inexflag_p (void) 3051 -- Function: int mpfr_erangeflag_p (void) 3052 Return the corresponding (underflow, overflow, divide-by-zero, 3053 invalid, inexact, _erange_) flag, which is non-zero iff the flag is 3054 set. 3055 3056 The ‘mpfr_flags_’ functions below that take an argument MASK can 3057operate on any subset of the exception flags: a flag is part of this 3058subset (or group) if and only if the corresponding bit of the argument 3059MASK is set. The ‘MPFR_FLAGS_’ macros will normally be used to build 3060this argument. *Note Exceptions::. 3061 3062 -- Function: void mpfr_flags_clear (mpfr_flags_t MASK) 3063 Clear (lower) the group of flags specified by MASK. 3064 3065 -- Function: void mpfr_flags_set (mpfr_flags_t MASK) 3066 Set (raise) the group of flags specified by MASK. 3067 3068 -- Function: mpfr_flags_t mpfr_flags_test (mpfr_flags_t MASK) 3069 Return the flags specified by MASK. To test whether any flag from 3070 MASK is set, compare the return value to 0. You can also test 3071 individual flags by AND’ing the result with ‘MPFR_FLAGS_’ macros. 3072 Example: 3073 mpfr_flags_t t = mpfr_flags_test (MPFR_FLAGS_UNDERFLOW| 3074 MPFR_FLAGS_OVERFLOW) 3075 ... 3076 if (t) /* underflow and/or overflow (unlikely) */ 3077 { 3078 if (t & MPFR_FLAGS_UNDERFLOW) { /* handle underflow */ } 3079 if (t & MPFR_FLAGS_OVERFLOW) { /* handle overflow */ } 3080 } 3081 3082 -- Function: mpfr_flags_t mpfr_flags_save (void) 3083 Return all the flags. It is equivalent to 3084 ‘mpfr_flags_test(MPFR_FLAGS_ALL)’. 3085 3086 -- Function: void mpfr_flags_restore (mpfr_flags_t FLAGS, mpfr_flags_t 3087 MASK) 3088 Restore the flags specified by MASK to their state represented in 3089 FLAGS. 3090 3091 3092File: mpfr.info, Node: Memory Handling Functions, Next: Compatibility with MPF, Prev: Exception Related Functions, Up: MPFR Interface 3093 30945.14 Memory Handling Functions 3095============================== 3096 3097These are general functions concerning memory handling (*note Memory 3098Handling::, for more information). 3099 3100 -- Function: void mpfr_free_cache (void) 3101 Free all caches and pools used by MPFR internally (those local to 3102 the current thread and those shared by all threads). You should 3103 call this function before terminating a thread, even if you did not 3104 call ‘mpfr_const_*’ functions directly (they could have been called 3105 internally). 3106 3107 -- Function: void mpfr_free_cache2 (mpfr_free_cache_t WAY) 3108 Free various caches and pools used by MPFR internally, as specified 3109 by WAY, which is a set of flags: 3110 • those local to the current thread if flag 3111 ‘MPFR_FREE_LOCAL_CACHE’ is set; 3112 • those shared by all threads if flag ‘MPFR_FREE_GLOBAL_CACHE’ 3113 is set. 3114 The other bits of WAY are currently ignored and are reserved for 3115 future use; they should be zero. 3116 3117 Note: 3118 ‘mpfr_free_cache2(MPFR_FREE_LOCAL_CACHE|MPFR_FREE_GLOBAL_CACHE)’ is 3119 currently equivalent to ‘mpfr_free_cache()’. 3120 3121 -- Function: void mpfr_free_pool (void) 3122 Free the pools used by MPFR internally. Note: This function is 3123 automatically called after the thread-local caches are freed (with 3124 ‘mpfr_free_cache’ or ‘mpfr_free_cache2’). 3125 3126 -- Function: int mpfr_mp_memory_cleanup (void) 3127 This function should be called before calling 3128 ‘mp_set_memory_functions’. *Note Memory Handling::, for more 3129 information. Zero is returned in case of success, non-zero in case 3130 of error. Errors are currently not possible, but checking the 3131 return value is recommended for future compatibility. 3132 3133 3134File: mpfr.info, Node: Compatibility with MPF, Next: Custom Interface, Prev: Memory Handling Functions, Up: MPFR Interface 3135 31365.15 Compatibility With MPF 3137=========================== 3138 3139A header file ‘mpf2mpfr.h’ is included in the distribution of MPFR for 3140compatibility with the GNU MP class MPF. By inserting the following two 3141lines after the ‘#include <gmp.h>’ line, 3142 #include <mpfr.h> 3143 #include <mpf2mpfr.h> 3144many programs written for MPF can be compiled directly against MPFR 3145without any changes. All operations are then performed with the default 3146MPFR rounding mode, which can be reset with 3147‘mpfr_set_default_rounding_mode’. 3148 3149 Warning! There are some differences. In particular: 3150 • The precision is different: MPFR rounds to the exact number of bits 3151 (zeroing trailing bits in the internal representation). Users may 3152 need to increase the precision of their variables. 3153 • The exponent range is also different. 3154 • The formatted output functions (‘gmp_printf’, etc.) will not work 3155 for arguments of arbitrary-precision floating-point type (‘mpf_t’, 3156 which ‘mpf2mpfr.h’ redefines as ‘mpfr_t’). 3157 • The output of ‘mpf_out_str’ has a format slightly different from 3158 the one of ‘mpfr_out_str’ (concerning the position of the 3159 decimal-point character, trailing zeros and the output of the value 3160 0). 3161 3162 -- Function: void mpfr_set_prec_raw (mpfr_t X, mpfr_prec_t PREC) 3163 Reset the precision of X to be *exactly* PREC bits. The only 3164 difference with ‘mpfr_set_prec’ is that PREC is assumed to be small 3165 enough so that the significand fits into the current allocated 3166 memory space for X. Otherwise the behavior is undefined. 3167 3168 -- Function: int mpfr_eq (mpfr_t OP1, mpfr_t OP2, unsigned long int 3169 OP3) 3170 Return non-zero if OP1 and OP2 are both non-zero ordinary numbers 3171 with the same exponent and the same first OP3 bits, both zero, or 3172 both infinities of the same sign. Return zero otherwise. This 3173 function is defined for compatibility with MPF, we do not recommend 3174 to use it otherwise. Do not use it either if you want to know 3175 whether two numbers are close to each other; for instance, 1.011111 3176 and 1.100000 are regarded as different for any value of OP3 larger 3177 than 1. 3178 3179 -- Function: void mpfr_reldiff (mpfr_t ROP, mpfr_t OP1, mpfr_t OP2, 3180 mpfr_rnd_t RND) 3181 Compute the relative difference between OP1 and OP2 and store the 3182 result in ROP. This function does not guarantee the correct 3183 rounding on the relative difference; it just computes 3184 |OP1-OP2|/OP1, using the precision of ROP and the rounding mode RND 3185 for all operations. 3186 3187 -- Function: int mpfr_mul_2exp (mpfr_t ROP, mpfr_t OP1, unsigned long 3188 int OP2, mpfr_rnd_t RND) 3189 -- Function: int mpfr_div_2exp (mpfr_t ROP, mpfr_t OP1, unsigned long 3190 int OP2, mpfr_rnd_t RND) 3191 These functions are identical to ‘mpfr_mul_2ui’ and ‘mpfr_div_2ui’ 3192 respectively. These functions are only kept for compatibility with 3193 MPF, one should prefer ‘mpfr_mul_2ui’ and ‘mpfr_div_2ui’ otherwise. 3194 3195 3196File: mpfr.info, Node: Custom Interface, Next: Internals, Prev: Compatibility with MPF, Up: MPFR Interface 3197 31985.16 Custom Interface 3199===================== 3200 3201Some applications use a stack to handle the memory and their objects. 3202However, the MPFR memory design is not well suited for such a thing. So 3203that such applications are able to use MPFR, an auxiliary memory 3204interface has been created: the Custom Interface. 3205 3206 The following interface allows one to use MPFR in two ways: 3207 3208 • Either directly store a floating-point number as a ‘mpfr_t’ on the 3209 stack. 3210 3211 • Either store its own representation on the stack and construct a 3212 new temporary ‘mpfr_t’ each time it is needed. 3213 3214 Nothing has to be done to destroy the floating-point numbers except 3215garbaging the used memory: all the memory management (allocating, 3216destroying, garbaging) is left to the application. 3217 3218 Each function in this interface is also implemented as a macro for 3219efficiency reasons: for example ‘mpfr_custom_init (s, p)’ uses the 3220macro, while ‘(mpfr_custom_init) (s, p)’ uses the function. 3221 3222 Note 1: MPFR functions may still initialize temporary floating-point 3223numbers using ‘mpfr_init’ and similar functions. See Custom Allocation 3224(GNU MP). 3225 3226 Note 2: MPFR functions may use the cached functions (‘mpfr_const_pi’ 3227for example), even if they are not explicitly called. You have to call 3228‘mpfr_free_cache’ each time you garbage the memory iff ‘mpfr_init’, 3229through GMP Custom Allocation, allocates its memory on the application 3230stack. 3231 3232 -- Function: size_t mpfr_custom_get_size (mpfr_prec_t PREC) 3233 Return the needed size in bytes to store the significand of a 3234 floating-point number of precision PREC. 3235 3236 -- Function: void mpfr_custom_init (void *SIGNIFICAND, mpfr_prec_t 3237 PREC) 3238 Initialize a significand of precision PREC, where SIGNIFICAND must 3239 be an area of ‘mpfr_custom_get_size (prec)’ bytes at least and be 3240 suitably aligned for an array of ‘mp_limb_t’ (GMP type, *note 3241 Internals::). 3242 3243 -- Function: void mpfr_custom_init_set (mpfr_t X, int KIND, mpfr_exp_t 3244 EXP, mpfr_prec_t PREC, void *SIGNIFICAND) 3245 Perform a dummy initialization of a ‘mpfr_t’ and set it to: 3246 • if abs(KIND) = ‘MPFR_NAN_KIND’, X is set to NaN; 3247 • if abs(KIND) = ‘MPFR_INF_KIND’, X is set to the infinity of 3248 the same sign as KIND; 3249 • if abs(KIND) = ‘MPFR_ZERO_KIND’, X is set to the zero of the 3250 same sign as KIND; 3251 • if abs(KIND) = ‘MPFR_REGULAR_KIND’, X is set to the regular 3252 number whose sign is the one of KIND, and whose exponent and 3253 significand are given by EXP and SIGNIFICAND. 3254 In all cases, SIGNIFICAND will be used directly for further 3255 computing involving X. This function does not allocate anything. 3256 A floating-point number initialized with this function cannot be 3257 resized using ‘mpfr_set_prec’ or ‘mpfr_prec_round’, or cleared 3258 using ‘mpfr_clear’! The SIGNIFICAND must have been initialized 3259 with ‘mpfr_custom_init’ using the same precision PREC. 3260 3261 -- Function: int mpfr_custom_get_kind (mpfr_t X) 3262 Return the current kind of a ‘mpfr_t’ as created by 3263 ‘mpfr_custom_init_set’. The behavior of this function for any 3264 ‘mpfr_t’ not initialized with ‘mpfr_custom_init_set’ is undefined. 3265 3266 -- Function: void * mpfr_custom_get_significand (mpfr_t X) 3267 Return a pointer to the significand used by a ‘mpfr_t’ initialized 3268 with ‘mpfr_custom_init_set’. The behavior of this function for any 3269 ‘mpfr_t’ not initialized with ‘mpfr_custom_init_set’ is undefined. 3270 3271 -- Function: mpfr_exp_t mpfr_custom_get_exp (mpfr_t X) 3272 Return the exponent of X, assuming that X is a non-zero ordinary 3273 number and the significand is considered in [1/2,1). But if X is 3274 NaN, infinity or zero, contrary to ‘mpfr_get_exp’ (where the 3275 behavior is undefined), the return value is here an unspecified, 3276 valid value of the ‘mpfr_exp_t’ type. The behavior of this 3277 function for any ‘mpfr_t’ not initialized with 3278 ‘mpfr_custom_init_set’ is undefined. 3279 3280 -- Function: void mpfr_custom_move (mpfr_t X, void *NEW_POSITION) 3281 Inform MPFR that the significand of X has moved due to a garbage 3282 collect and update its new position to ‘new_position’. However the 3283 application has to move the significand and the ‘mpfr_t’ itself. 3284 The behavior of this function for any ‘mpfr_t’ not initialized with 3285 ‘mpfr_custom_init_set’ is undefined. 3286 3287 3288File: mpfr.info, Node: Internals, Prev: Custom Interface, Up: MPFR Interface 3289 32905.17 Internals 3291============== 3292 3293A “limb” means the part of a multi-precision number that fits in a 3294single word. Usually a limb contains 32 or 64 bits. The C data type 3295for a limb is ‘mp_limb_t’. 3296 3297 The ‘mpfr_t’ type is internally defined as a one-element array of a 3298structure, and ‘mpfr_ptr’ is the C data type representing a pointer to 3299this structure. The ‘mpfr_t’ type consists of four fields: 3300 3301 • The ‘_mpfr_prec’ field is used to store the precision of the 3302 variable (in bits); this is not less than ‘MPFR_PREC_MIN’. 3303 3304 • The ‘_mpfr_sign’ field is used to store the sign of the variable. 3305 3306 • The ‘_mpfr_exp’ field stores the exponent. An exponent of 0 means 3307 a radix point just above the most significant limb. Non-zero 3308 values n are a multiplier 2^n relative to that point. A NaN, an 3309 infinity and a zero are indicated by special values of the exponent 3310 field. 3311 3312 • Finally, the ‘_mpfr_d’ field is a pointer to the limbs, least 3313 significant limbs stored first. The number of limbs in use is 3314 controlled by ‘_mpfr_prec’, namely 3315 ceil(‘_mpfr_prec’/‘mp_bits_per_limb’). Non-singular (i.e., 3316 different from NaN, Infinity or zero) values always have the most 3317 significant bit of the most significant limb set to 1. When the 3318 precision does not correspond to a whole number of limbs, the 3319 excess bits at the low end of the data are zeros. 3320 3321 3322File: mpfr.info, Node: API Compatibility, Next: MPFR and the IEEE 754 Standard, Prev: MPFR Interface, Up: Top 3323 33246 API Compatibility 3325******************* 3326 3327The goal of this section is to describe some API changes that occurred 3328from one version of MPFR to another, and how to write code that can be 3329compiled and run with older MPFR versions. The minimum MPFR version 3330that is considered here is 2.2.0 (released on 20 September 2005). 3331 3332 API changes can only occur between major or minor versions. Thus the 3333patchlevel (the third number in the MPFR version) will be ignored in the 3334following. If a program does not use MPFR internals, changes in the 3335behavior between two versions differing only by the patchlevel should 3336only result from what was regarded as a bug or unspecified behavior. 3337 3338 As a general rule, a program written for some MPFR version should 3339work with later versions, possibly except at a new major version, where 3340some features (described as obsolete for some time) can be removed. In 3341such a case, a failure should occur during compilation or linking. If a 3342result becomes incorrect because of such a change, please look at the 3343various changes below (they are minimal, and most software should be 3344unaffected), at the FAQ and at the MPFR web page for your version (a bug 3345could have been introduced and be already fixed); and if the problem is 3346not mentioned, please send us a bug report (*note Reporting Bugs::). 3347 3348 However, a program written for the current MPFR version (as 3349documented by this manual) may not necessarily work with previous 3350versions of MPFR. This section should help developers to write portable 3351code. 3352 3353 Note: Information given here may be incomplete. API changes are also 3354described in the NEWS file (for each version, instead of being 3355classified like here), together with other changes. 3356 3357* Menu: 3358 3359* Type and Macro Changes:: 3360* Added Functions:: 3361* Changed Functions:: 3362* Removed Functions:: 3363* Other Changes:: 3364 3365 3366File: mpfr.info, Node: Type and Macro Changes, Next: Added Functions, Prev: API Compatibility, Up: API Compatibility 3367 33686.1 Type and Macro Changes 3369========================== 3370 3371The official type for exponent values changed from ‘mp_exp_t’ to 3372‘mpfr_exp_t’ in MPFR 3.0. The type ‘mp_exp_t’ will remain available as 3373it comes from GMP (with a different meaning). These types are currently 3374the same (‘mpfr_exp_t’ is defined as ‘mp_exp_t’ with ‘typedef’), so that 3375programs can still use ‘mp_exp_t’; but this may change in the future. 3376Alternatively, using the following code after including ‘mpfr.h’ will 3377work with official MPFR versions, as ‘mpfr_exp_t’ was never defined in 3378MPFR 2.x: 3379 #if MPFR_VERSION_MAJOR < 3 3380 typedef mp_exp_t mpfr_exp_t; 3381 #endif 3382 3383 The official types for precision values and for rounding modes 3384respectively changed from ‘mp_prec_t’ and ‘mp_rnd_t’ to ‘mpfr_prec_t’ 3385and ‘mpfr_rnd_t’ in MPFR 3.0. This change was actually done a long time 3386ago in MPFR, at least since MPFR 2.2.0, with the following code in 3387‘mpfr.h’: 3388 #ifndef mp_rnd_t 3389 # define mp_rnd_t mpfr_rnd_t 3390 #endif 3391 #ifndef mp_prec_t 3392 # define mp_prec_t mpfr_prec_t 3393 #endif 3394 This means that it is safe to use the new official types 3395‘mpfr_prec_t’ and ‘mpfr_rnd_t’ in your programs. The types ‘mp_prec_t’ 3396and ‘mp_rnd_t’ (defined in MPFR only) may be removed in the future, as 3397the prefix ‘mp_’ is reserved by GMP. 3398 3399 The precision type ‘mpfr_prec_t’ (‘mp_prec_t’) was unsigned before 3400MPFR 3.0; it is now signed. ‘MPFR_PREC_MAX’ has not changed, though. 3401Indeed the MPFR code requires that ‘MPFR_PREC_MAX’ be representable in 3402the exponent type, which may have the same size as ‘mpfr_prec_t’ but has 3403always been signed. The consequence is that valid code that does not 3404assume anything about the signedness of ‘mpfr_prec_t’ should work with 3405past and new MPFR versions. This change was useful as the use of 3406unsigned types tends to convert signed values to unsigned ones in 3407expressions due to the usual arithmetic conversions, which can yield 3408incorrect results if a negative value is converted in such a way. 3409Warning! A program assuming (intentionally or not) that ‘mpfr_prec_t’ 3410is signed may be affected by this problem when it is built and run 3411against MPFR 2.x. 3412 3413 The rounding modes ‘GMP_RNDx’ were renamed to ‘MPFR_RNDx’ in 3414MPFR 3.0. However the old names ‘GMP_RNDx’ have been kept for 3415compatibility (this might change in future versions), using: 3416 #define GMP_RNDN MPFR_RNDN 3417 #define GMP_RNDZ MPFR_RNDZ 3418 #define GMP_RNDU MPFR_RNDU 3419 #define GMP_RNDD MPFR_RNDD 3420 The rounding mode “round away from zero” (‘MPFR_RNDA’) was added in 3421MPFR 3.0 (however no rounding mode ‘GMP_RNDA’ exists). Faithful 3422rounding (‘MPFR_RNDF’) was added in MPFR 4.0, but currently, it is 3423partially supported. 3424 3425 The flags-related macros, whose name starts with ‘MPFR_FLAGS_’, were 3426added in MPFR 4.0 (for the new functions ‘mpfr_flags_clear’, 3427‘mpfr_flags_restore’, ‘mpfr_flags_set’ and ‘mpfr_flags_test’, in 3428particular). 3429 3430 3431File: mpfr.info, Node: Added Functions, Next: Changed Functions, Prev: Type and Macro Changes, Up: API Compatibility 3432 34336.2 Added Functions 3434=================== 3435 3436We give here in alphabetical order the functions (and function-like 3437macros) that were added after MPFR 2.2, and in which MPFR version. 3438 3439 • ‘mpfr_add_d’ in MPFR 2.4. 3440 3441 • ‘mpfr_ai’ in MPFR 3.0 (incomplete, experimental). 3442 3443 • ‘mpfr_asprintf’ in MPFR 2.4. 3444 3445 • ‘mpfr_beta’ in MPFR 4.0 (incomplete, experimental). 3446 3447 • ‘mpfr_buildopt_decimal_p’ in MPFR 3.0. 3448 3449 • ‘mpfr_buildopt_float128_p’ in MPFR 4.0. 3450 3451 • ‘mpfr_buildopt_gmpinternals_p’ in MPFR 3.1. 3452 3453 • ‘mpfr_buildopt_sharedcache_p’ in MPFR 4.0. 3454 3455 • ‘mpfr_buildopt_tls_p’ in MPFR 3.0. 3456 3457 • ‘mpfr_buildopt_tune_case’ in MPFR 3.1. 3458 3459 • ‘mpfr_clear_divby0’ in MPFR 3.1 (new divide-by-zero exception). 3460 3461 • ‘mpfr_cmpabs_ui’ in MPFR 4.1. 3462 3463 • ‘mpfr_copysign’ in MPFR 2.3. Note: MPFR 2.2 had a ‘mpfr_copysign’ 3464 function that was available, but not documented, and with a slight 3465 difference in the semantics (when the second input operand is a 3466 NaN). 3467 3468 • ‘mpfr_custom_get_significand’ in MPFR 3.0. This function was named 3469 ‘mpfr_custom_get_mantissa’ in previous versions; 3470 ‘mpfr_custom_get_mantissa’ is still available via a macro in 3471 ‘mpfr.h’: 3472 #define mpfr_custom_get_mantissa mpfr_custom_get_significand 3473 Thus code that needs to work with both MPFR 2.x and MPFR 3.x should 3474 use ‘mpfr_custom_get_mantissa’. 3475 3476 • ‘mpfr_d_div’ and ‘mpfr_d_sub’ in MPFR 2.4. 3477 3478 • ‘mpfr_digamma’ in MPFR 3.0. 3479 3480 • ‘mpfr_divby0_p’ in MPFR 3.1 (new divide-by-zero exception). 3481 3482 • ‘mpfr_div_d’ in MPFR 2.4. 3483 3484 • ‘mpfr_dot’ in MPFR 4.1 (incomplete, experimental). 3485 3486 • ‘mpfr_erandom’ in MPFR 4.0. 3487 3488 • ‘mpfr_flags_clear’, ‘mpfr_flags_restore’, ‘mpfr_flags_save’, 3489 ‘mpfr_flags_set’ and ‘mpfr_flags_test’ in MPFR 4.0. 3490 3491 • ‘mpfr_fmma’ and ‘mpfr_fmms’ in MPFR 4.0. 3492 3493 • ‘mpfr_fmod’ in MPFR 2.4. 3494 3495 • ‘mpfr_fmodquo’ in MPFR 4.0. 3496 3497 • ‘mpfr_fms’ in MPFR 2.3. 3498 3499 • ‘mpfr_fpif_export’ and ‘mpfr_fpif_import’ in MPFR 4.0. 3500 3501 • ‘mpfr_fprintf’ in MPFR 2.4. 3502 3503 • ‘mpfr_free_cache2’ in MPFR 4.0. 3504 3505 • ‘mpfr_free_pool’ in MPFR 4.0. 3506 3507 • ‘mpfr_frexp’ in MPFR 3.1. 3508 3509 • ‘mpfr_gamma_inc’ in MPFR 4.0. 3510 3511 • ‘mpfr_get_decimal128’ in MPFR 4.1. 3512 3513 • ‘mpfr_get_float128’ in MPFR 4.0 if configured with 3514 ‘--enable-float128’. 3515 3516 • ‘mpfr_get_flt’ in MPFR 3.0. 3517 3518 • ‘mpfr_get_patches’ in MPFR 2.3. 3519 3520 • ‘mpfr_get_q’ in MPFR 4.0. 3521 3522 • ‘mpfr_get_str_ndigits’ in MPFR 4.1. 3523 3524 • ‘mpfr_get_z_2exp’ in MPFR 3.0. This function was named 3525 ‘mpfr_get_z_exp’ in previous versions; ‘mpfr_get_z_exp’ is still 3526 available via a macro in ‘mpfr.h’: 3527 #define mpfr_get_z_exp mpfr_get_z_2exp 3528 Thus code that needs to work with both MPFR 2.x and MPFR 3.x should 3529 use ‘mpfr_get_z_exp’. 3530 3531 • ‘mpfr_grandom’ in MPFR 3.1. 3532 3533 • ‘mpfr_j0’, ‘mpfr_j1’ and ‘mpfr_jn’ in MPFR 2.3. 3534 3535 • ‘mpfr_lgamma’ in MPFR 2.3. 3536 3537 • ‘mpfr_li2’ in MPFR 2.4. 3538 3539 • ‘mpfr_log_ui’ in MPFR 4.0. 3540 3541 • ‘mpfr_min_prec’ in MPFR 3.0. 3542 3543 • ‘mpfr_modf’ in MPFR 2.4. 3544 3545 • ‘mpfr_mp_memory_cleanup’ in MPFR 4.0. 3546 3547 • ‘mpfr_mul_d’ in MPFR 2.4. 3548 3549 • ‘mpfr_nrandom’ in MPFR 4.0. 3550 3551 • ‘mpfr_printf’ in MPFR 2.4. 3552 3553 • ‘mpfr_rec_sqrt’ in MPFR 2.4. 3554 3555 • ‘mpfr_regular_p’ in MPFR 3.0. 3556 3557 • ‘mpfr_remainder’ and ‘mpfr_remquo’ in MPFR 2.3. 3558 3559 • ‘mpfr_rint_roundeven’ and ‘mpfr_roundeven’ in MPFR 4.0. 3560 3561 • ‘mpfr_round_nearest_away’ in MPFR 4.0. 3562 3563 • ‘mpfr_rootn_ui’ in MPFR 4.0. 3564 3565 • ‘mpfr_set_decimal128’ in MPFR 4.1. 3566 3567 • ‘mpfr_set_divby0’ in MPFR 3.1 (new divide-by-zero exception). 3568 3569 • ‘mpfr_set_float128’ in MPFR 4.0 if configured with 3570 ‘--enable-float128’. 3571 3572 • ‘mpfr_set_flt’ in MPFR 3.0. 3573 3574 • ‘mpfr_set_z_2exp’ in MPFR 3.0. 3575 3576 • ‘mpfr_set_zero’ in MPFR 3.0. 3577 3578 • ‘mpfr_setsign’ in MPFR 2.3. 3579 3580 • ‘mpfr_signbit’ in MPFR 2.3. 3581 3582 • ‘mpfr_sinh_cosh’ in MPFR 2.4. 3583 3584 • ‘mpfr_snprintf’ and ‘mpfr_sprintf’ in MPFR 2.4. 3585 3586 • ‘mpfr_sub_d’ in MPFR 2.4. 3587 3588 • ‘mpfr_total_order_p’ in MPFR 4.1. 3589 3590 • ‘mpfr_urandom’ in MPFR 3.0. 3591 3592 • ‘mpfr_vasprintf’, ‘mpfr_vfprintf’, ‘mpfr_vprintf’, ‘mpfr_vsprintf’ 3593 and ‘mpfr_vsnprintf’ in MPFR 2.4. 3594 3595 • ‘mpfr_y0’, ‘mpfr_y1’ and ‘mpfr_yn’ in MPFR 2.3. 3596 3597 • ‘mpfr_z_sub’ in MPFR 3.1. 3598 3599 3600File: mpfr.info, Node: Changed Functions, Next: Removed Functions, Prev: Added Functions, Up: API Compatibility 3601 36026.3 Changed Functions 3603===================== 3604 3605The following functions have changed after MPFR 2.2. Changes can affect 3606the behavior of code written for some MPFR version when built and run 3607against another MPFR version (older or newer), as described below. 3608 3609 • The formatted output functions (‘mpfr_printf’, etc.) have slightly 3610 changed in MPFR 4.1 in the case where the precision field is empty: 3611 trailing zeros were not output with the conversion specifier ‘e’ / 3612 ‘E’ (the chosen precision was not fully specified and it depended 3613 on the input value), and also on the value zero with the conversion 3614 specifiers ‘f’ / ‘F’ / ‘g’ / ‘G’ (this could partly be regarded as 3615 a bug); they are now kept in a way similar to the formatted output 3616 functions from C. 3617 3618 • ‘mpfr_abs’, ‘mpfr_neg’ and ‘mpfr_set’ changed in MPFR 4.0. In 3619 previous MPFR versions, the sign bit of a NaN was unspecified; 3620 however, in practice, it was set as now specified except for 3621 ‘mpfr_neg’ with a reused argument: ‘mpfr_neg(x,x,rnd)’. 3622 3623 • ‘mpfr_check_range’ changed in MPFR 2.3.2 and MPFR 2.4. If the 3624 value is an inexact infinity, the overflow flag is now set (in case 3625 it was lost), while it was previously left unchanged. This is 3626 really what is expected in practice (and what the MPFR code was 3627 expecting), so that the previous behavior was regarded as a bug. 3628 Hence the change in MPFR 2.3.2. 3629 3630 • ‘mpfr_eint’ changed in MPFR 4.0. This function now returns the 3631 value of the E1/eint1 function for negative argument (before 3632 MPFR 4.0, it was returning NaN). 3633 3634 • ‘mpfr_get_f’ changed in MPFR 3.0. This function was returning 3635 zero, except for NaN and Inf, which do not exist in MPF. The 3636 _erange_ flag is now set in these cases, and ‘mpfr_get_f’ now 3637 returns the usual ternary value. 3638 3639 • ‘mpfr_get_si’, ‘mpfr_get_sj’, ‘mpfr_get_ui’ and ‘mpfr_get_uj’ 3640 changed in MPFR 3.0. In previous MPFR versions, the cases where 3641 the _erange_ flag is set were unspecified. 3642 3643 • ‘mpfr_get_str’ changed in MPFR 4.0. This function now sets the NaN 3644 flag on NaN input (to follow the usual MPFR rules on NaN and 3645 IEEE 754-2008 recommendations on string conversions from 3646 Subclause 5.12.1) and sets the inexact flag when the conversion is 3647 inexact. 3648 3649 • ‘mpfr_get_z’ changed in MPFR 3.0. The return type was ‘void’; it 3650 is now ‘int’, and the usual ternary value is returned. Thus 3651 programs that need to work with both MPFR 2.x and 3.x must not use 3652 the return value. Even in this case, C code using ‘mpfr_get_z’ as 3653 the second or third term of a conditional operator may also be 3654 affected. For instance, the following is correct with MPFR 3.0, 3655 but not with MPFR 2.x: 3656 bool ? mpfr_get_z(...) : mpfr_add(...); 3657 On the other hand, the following is correct with MPFR 2.x, but not 3658 with MPFR 3.0: 3659 bool ? mpfr_get_z(...) : (void) mpfr_add(...); 3660 Portable code should cast ‘mpfr_get_z(...)’ to ‘void’ to use the 3661 type ‘void’ for both terms of the conditional operator, as in: 3662 bool ? (void) mpfr_get_z(...) : (void) mpfr_add(...); 3663 Alternatively, ‘if ... else’ can be used instead of the conditional 3664 operator. 3665 3666 Moreover the cases where the _erange_ flag is set were unspecified 3667 in MPFR 2.x. 3668 3669 • ‘mpfr_get_z_exp’ changed in MPFR 3.0. In previous MPFR versions, 3670 the cases where the _erange_ flag is set were unspecified. Note: 3671 this function has been renamed to ‘mpfr_get_z_2exp’ in MPFR 3.0, 3672 but ‘mpfr_get_z_exp’ is still available for compatibility reasons. 3673 3674 • ‘mpfr_out_str’ changed in MPFR 4.1. The argument BASE can now be 3675 negative (from −2 to −36), in order to follow ‘mpfr_get_str’ and 3676 GMP’s ‘mpf_out_str’ functions. 3677 3678 • ‘mpfr_set_exp’ changed in MPFR 4.0. Before MPFR 4.0, the exponent 3679 was set whatever the contents of the MPFR object in argument. In 3680 practice, this could be useful as a low-level function when the 3681 MPFR number was being constructed by setting the fields of its 3682 internal structure, but the API does not provide a way to do this 3683 except by using internals. Thus, for the API, this behavior was 3684 useless and could quickly lead to undefined behavior due to the 3685 fact that the generated value could have an invalid format if the 3686 MPFR object contained a special value (NaN, infinity or zero). 3687 3688 • ‘mpfr_strtofr’ changed in MPFR 2.3.1 and MPFR 2.4. This was 3689 actually a bug fix since the code and the documentation did not 3690 match. But both were changed in order to have a more consistent 3691 and useful behavior. The main changes in the code are as follows. 3692 The binary exponent is now accepted even without the ‘0b’ or ‘0x’ 3693 prefix. Data corresponding to NaN can now have an optional sign 3694 (such data were previously invalid). 3695 3696 • ‘mpfr_strtofr’ changed in MPFR 3.0. This function now accepts 3697 bases from 37 to 62 (no changes for the other bases). Note: if an 3698 unsupported base is provided to this function, the behavior is 3699 undefined; more precisely, in MPFR 2.3.1 and later, providing an 3700 unsupported base yields an assertion failure (this behavior may 3701 change in the future). 3702 3703 • ‘mpfr_subnormalize’ changed in MPFR 3.1. This was actually 3704 regarded as a bug fix. The ‘mpfr_subnormalize’ implementation up 3705 to MPFR 3.0.0 did not change the flags. In particular, it did not 3706 follow the generic rule concerning the inexact flag (and no special 3707 behavior was specified). The case of the underflow flag was more a 3708 lack of specification. 3709 3710 • ‘mpfr_sum’ changed in MPFR 4.0. The ‘mpfr_sum’ function has 3711 completely been rewritten for MPFR 4.0, with an update of the 3712 specification: the sign of an exact zero result is now specified, 3713 and the return value is now the usual ternary value. The old 3714 ‘mpfr_sum’ implementation could also take all the memory and crash 3715 on inputs of very different magnitude. 3716 3717 • ‘mpfr_urandom’ and ‘mpfr_urandomb’ changed in MPFR 3.1. Their 3718 behavior no longer depends on the platform (assuming this is also 3719 true for GMP’s random generator, which is not the case between GMP 3720 4.1 and 4.2 if ‘gmp_randinit_default’ is used). As a consequence, 3721 the returned values can be different between MPFR 3.1 and previous 3722 MPFR versions. Note: as the reproducibility of these functions was 3723 not specified before MPFR 3.1, the MPFR 3.1 behavior is _not_ 3724 regarded as backward incompatible with previous versions. 3725 3726 • ‘mpfr_urandom’ changed in MPFR 4.0. The next random state no 3727 longer depends on the current exponent range and the rounding mode. 3728 The exceptions due to the rounding of the random number are now 3729 correctly generated, following the uniform distribution. As a 3730 consequence, the returned values can be different between MPFR 4.0 3731 and previous MPFR versions. 3732 3733 3734File: mpfr.info, Node: Removed Functions, Next: Other Changes, Prev: Changed Functions, Up: API Compatibility 3735 37366.4 Removed Functions 3737===================== 3738 3739Functions ‘mpfr_random’ and ‘mpfr_random2’ have been removed in MPFR 3.0 3740(this only affects old code built against MPFR 3.0 or later). (The 3741function ‘mpfr_random’ had been deprecated since at least MPFR 2.2.0, 3742and ‘mpfr_random2’ since MPFR 2.4.0.) 3743 3744 Macros ‘mpfr_add_one_ulp’ and ‘mpfr_sub_one_ulp’ have been removed in 3745MPFR 4.0. They were no longer documented since MPFR 2.1.0 and were 3746announced as deprecated since MPFR 3.1.0. 3747 3748 Function ‘mpfr_grandom’ is marked as deprecated in MPFR 4.0. It will 3749be removed in a future release. 3750 3751 3752File: mpfr.info, Node: Other Changes, Prev: Removed Functions, Up: API Compatibility 3753 37546.5 Other Changes 3755================= 3756 3757For users of a C++ compiler, the way how the availability of ‘intmax_t’ 3758is detected has changed in MPFR 3.0. In MPFR 2.x, if a macro ‘INTMAX_C’ 3759or ‘UINTMAX_C’ was defined (e.g. when the ‘__STDC_CONSTANT_MACROS’ 3760macro had been defined before ‘<stdint.h>’ or ‘<inttypes.h>’ has been 3761included), ‘intmax_t’ was assumed to be defined. However this was not 3762always the case (more precisely, ‘intmax_t’ can be defined only in the 3763namespace ‘std’, as with Boost), so that compilations could fail. Thus 3764the check for ‘INTMAX_C’ or ‘UINTMAX_C’ is now disabled for C++ 3765compilers, with the following consequences: 3766 3767 • Programs written for MPFR 2.x that need ‘intmax_t’ may no longer be 3768 compiled against MPFR 3.0: a ‘#define MPFR_USE_INTMAX_T’ may be 3769 necessary before ‘mpfr.h’ is included. 3770 3771 • The compilation of programs that work with MPFR 3.0 may fail with 3772 MPFR 2.x due to the problem described above. Workarounds are 3773 possible, such as defining ‘intmax_t’ and ‘uintmax_t’ in the global 3774 namespace, though this is not clean. 3775 3776 The divide-by-zero exception is new in MPFR 3.1. However it should 3777not introduce incompatible changes for programs that strictly follow the 3778MPFR API since the exception can only be seen via new functions. 3779 3780 As of MPFR 3.1, the ‘mpfr.h’ header can be included several times, 3781while still supporting optional functions (*note Headers and 3782Libraries::). 3783 3784 The way memory is allocated by MPFR should be regarded as 3785well-specified only as of MPFR 4.0. 3786 3787 3788File: mpfr.info, Node: MPFR and the IEEE 754 Standard, Next: Contributors, Prev: API Compatibility, Up: Top 3789 37907 MPFR and the IEEE 754 Standard 3791******************************** 3792 3793This section describes differences between MPFR and the IEEE 754 3794standard, and behaviors that are not specified yet in IEEE 754. 3795 3796 The MPFR numbers do not include subnormals. The reason is that 3797subnormals are less useful than in IEEE 754 as the default exponent 3798range in MPFR is large and they would have made the implementation more 3799complex. However, subnormals can be emulated using ‘mpfr_subnormalize’. 3800 3801 MPFR has a single NaN. The behavior is similar either to a signaling 3802NaN or to a quiet NaN, depending on the context. For any function 3803returning a NaN (either produced or propagated), the NaN flag is set, 3804while in IEEE 754, some operations are quiet (even on a signaling NaN). 3805 3806 The ‘mpfr_rec_sqrt’ function differs from IEEE 754 on −0, where it 3807gives +Inf (like for +0), following the usual limit rules, instead of 3808−Inf. 3809 3810 The ‘mpfr_root’ function predates IEEE 754-2008 and behaves 3811differently from its rootn operation. It is deprecated and 3812‘mpfr_rootn_ui’ should be used instead. 3813 3814 Operations with an unsigned zero: For functions taking an argument of 3815integer or rational type, a zero of such a type is unsigned unlike the 3816floating-point zero (this includes the zero of type ‘unsigned long’, 3817which is a mathematical, exact zero, as opposed to a floating-point 3818zero, which may come from an underflow and whose sign would correspond 3819to the sign of the real non-zero value). Unless documented otherwise, 3820this zero is regarded as +0, as if it were first converted to a MPFR 3821number with ‘mpfr_set_ui’ or ‘mpfr_set_si’ (thus the result may not 3822agree with the usual limit rules applied to a mathematical zero). This 3823is not the case of addition and subtraction (‘mpfr_add_ui’, etc.), but 3824for these functions, only the sign of a zero result would be affected, 3825with +0 and −0 considered equal. Such operations are currently out of 3826the scope of the IEEE 754 standard, and at the time of specification in 3827MPFR, the Floating-Point Working Group in charge of the revision of 3828IEEE 754 did not want to discuss issues with non-floating-point types in 3829general. 3830 3831 Note also that some obvious differences may come from the fact that 3832in MPFR, each variable has its own precision. For instance, a 3833subtraction of two numbers of the same sign may yield an overflow; idem 3834for a call to ‘mpfr_set’, ‘mpfr_neg’ or ‘mpfr_abs’, if the destination 3835variable has a smaller precision. 3836 3837 3838File: mpfr.info, Node: Contributors, Next: References, Prev: MPFR and the IEEE 754 Standard, Up: Top 3839 3840Contributors 3841************ 3842 3843The main developers of MPFR are Guillaume Hanrot, Vincent Lefèvre, 3844Patrick Pélissier, Philippe Théveny and Paul Zimmermann. 3845 3846 Sylvie Boldo from ENS-Lyon, France, contributed the functions 3847‘mpfr_agm’ and ‘mpfr_log’. Sylvain Chevillard contributed the ‘mpfr_ai’ 3848function. David Daney contributed the hyperbolic and inverse hyperbolic 3849functions, the base-2 exponential, and the factorial function. Alain 3850Delplanque contributed the new version of the ‘mpfr_get_str’ function. 3851Mathieu Dutour contributed the functions ‘mpfr_acos’, ‘mpfr_asin’ and 3852‘mpfr_atan’, and a previous version of ‘mpfr_gamma’. Laurent Fousse 3853contributed the original version of the ‘mpfr_sum’ function (used up to 3854MPFR 3.1). Emmanuel Jeandel, from ENS-Lyon too, contributed the generic 3855hypergeometric code, as well as the internal function ‘mpfr_exp3’, a 3856first implementation of the sine and cosine, and improved versions of 3857‘mpfr_const_log2’ and ‘mpfr_const_pi’. Ludovic Meunier helped in the 3858design of the ‘mpfr_erf’ code. Jean-Luc Rémy contributed the 3859‘mpfr_zeta’ code. Fabrice Rouillier contributed the ‘mpfr_xxx_z’ and 3860‘mpfr_xxx_q’ functions, and helped to the Microsoft Windows porting. 3861Damien Stehlé contributed the ‘mpfr_get_ld_2exp’ function. Charles 3862Karney contributed the ‘mpfr_nrandom’ and ‘mpfr_erandom’ functions. 3863 3864 We would like to thank Jean-Michel Muller and Joris van der Hoeven 3865for very fruitful discussions at the beginning of that project, Torbjörn 3866Granlund and Kevin Ryde for their help about design issues, and Nathalie 3867Revol for her careful reading of a previous version of this 3868documentation. In particular Kevin Ryde did a tremendous job for the 3869portability of MPFR in 2002-2004. 3870 3871 The development of the MPFR library would not have been possible 3872without the continuous support of INRIA, and of the LORIA (Nancy, 3873France) and LIP (Lyon, France) laboratories. In particular the main 3874authors were or are members of the PolKA, Spaces, Cacao, Caramel and 3875Caramba project-teams at LORIA and of the Arénaire and AriC 3876project-teams at LIP. This project was started during the Fiable 3877(reliable in French) action supported by INRIA, and continued during the 3878AOC action. The development of MPFR was also supported by a grant 3879(202F0659 00 MPN 121) from the Conseil Régional de Lorraine in 2002, 3880from INRIA by an "associate engineer" grant (2003-2005), an "opération 3881de développement logiciel" grant (2007-2009), and the post-doctoral 3882grant of Sylvain Chevillard in 2009-2010. The MPFR-MPC workshop in June 38832012 was partly supported by the ERC grant ANTICS of Andreas Enge. The 3884MPFR-MPC workshop in January 2013 was partly supported by the ERC grant 3885ANTICS, the GDR IM and the Caramel project-team, during which Mickaël 3886Gastineau contributed the MPFRbench program, Fredrik Johansson a faster 3887version of ‘mpfr_const_euler’, and Jianyang Pan a formally proven 3888version of the ‘mpfr_add1sp1’ internal routine. 3889 3890 3891File: mpfr.info, Node: References, Next: GNU Free Documentation License, Prev: Contributors, Up: Top 3892 3893References 3894********** 3895 3896 • Richard Brent and Paul Zimmermann, "Modern Computer Arithmetic", 3897 Cambridge University Press, Cambridge Monographs on Applied and 3898 Computational Mathematics, Number 18, 2010. Electronic version 3899 freely available at 3900 <https://members.loria.fr/PZimmermann/mca/pub226.html>. 3901 3902 • Laurent Fousse, Guillaume Hanrot, Vincent Lefèvre, Patrick 3903 Pélissier and Paul Zimmermann, "MPFR: A Multiple-Precision Binary 3904 Floating-Point Library With Correct Rounding", ACM Transactions on 3905 Mathematical Software, volume 33, issue 2, article 13, 15 pages, 3906 2007, <https://doi.org/10.1145/1236463.1236468>. 3907 3908 • Torbjörn Granlund, "GNU MP: The GNU Multiple Precision Arithmetic 3909 Library", version 6.1.2, 2016, <https://gmplib.org/>. 3910 3911 • IEEE standard for binary floating-point arithmetic, Technical 3912 Report ANSI-IEEE Standard 754-1985, New York, 1985. Approved March 3913 21, 1985: IEEE Standards Board; approved July 26, 1985: American 3914 National Standards Institute, 18 pages. 3915 3916 • IEEE Standard for Floating-Point Arithmetic, ANSI-IEEE Standard 3917 754-2008, 2008. Revision of ANSI-IEEE Standard 754-1985, approved 3918 June 12, 2008: IEEE Standards Board, 70 pages. 3919 3920 • Donald E. Knuth, "The Art of Computer Programming", vol 2, 3921 "Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981. 3922 3923 • Jean-Michel Muller, "Elementary Functions, Algorithms and 3924 Implementation", Birkhäuser, Boston, 3rd edition, 2016. 3925 3926 • Jean-Michel Muller, Nicolas Brisebarre, Florent de Dinechin, 3927 Claude-Pierre Jeannerod, Vincent Lefèvre, Guillaume Melquiond, 3928 Nathalie Revol, Damien Stehlé and Serge Torrès, "Handbook of 3929 Floating-Point Arithmetic", Birkhäuser, Boston, 2009. 3930 3931 3932File: mpfr.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: References, Up: Top 3933 3934Appendix A GNU Free Documentation License 3935***************************************** 3936 3937 Version 1.2, November 2002 3938 3939 Copyright © 2000,2001,2002 Free Software Foundation, Inc. 3940 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA 3941 3942 Everyone is permitted to copy and distribute verbatim copies 3943 of this license document, but changing it is not allowed. 3944 3945 0. PREAMBLE 3946 3947 The purpose of this License is to make a manual, textbook, or other 3948 functional and useful document “free” in the sense of freedom: to 3949 assure everyone the effective freedom to copy and redistribute it, 3950 with or without modifying it, either commercially or 3951 noncommercially. Secondarily, this License preserves for the 3952 author and publisher a way to get credit for their work, while not 3953 being considered responsible for modifications made by others. 3954 3955 This License is a kind of “copyleft”, which means that derivative 3956 works of the document must themselves be free in the same sense. 3957 It complements the GNU General Public License, which is a copyleft 3958 license designed for free software. 3959 3960 We have designed this License in order to use it for manuals for 3961 free software, because free software needs free documentation: a 3962 free program should come with manuals providing the same freedoms 3963 that the software does. But this License is not limited to 3964 software manuals; it can be used for any textual work, regardless 3965 of subject matter or whether it is published as a printed book. We 3966 recommend this License principally for works whose purpose is 3967 instruction or reference. 3968 3969 1. APPLICABILITY AND DEFINITIONS 3970 3971 This License applies to any manual or other work, in any medium, 3972 that contains a notice placed by the copyright holder saying it can 3973 be distributed under the terms of this License. Such a notice 3974 grants a world-wide, royalty-free license, unlimited in duration, 3975 to use that work under the conditions stated herein. The 3976 “Document”, below, refers to any such manual or work. Any member 3977 of the public is a licensee, and is addressed as “you”. You accept 3978 the license if you copy, modify or distribute the work in a way 3979 requiring permission under copyright law. 3980 3981 A “Modified Version” of the Document means any work containing the 3982 Document or a portion of it, either copied verbatim, or with 3983 modifications and/or translated into another language. 3984 3985 A “Secondary Section” is a named appendix or a front-matter section 3986 of the Document that deals exclusively with the relationship of the 3987 publishers or authors of the Document to the Document’s overall 3988 subject (or to related matters) and contains nothing that could 3989 fall directly within that overall subject. (Thus, if the Document 3990 is in part a textbook of mathematics, a Secondary Section may not 3991 explain any mathematics.) The relationship could be a matter of 3992 historical connection with the subject or with related matters, or 3993 of legal, commercial, philosophical, ethical or political position 3994 regarding them. 3995 3996 The “Invariant Sections” are certain Secondary Sections whose 3997 titles are designated, as being those of Invariant Sections, in the 3998 notice that says that the Document is released under this License. 3999 If a section does not fit the above definition of Secondary then it 4000 is not allowed to be designated as Invariant. The Document may 4001 contain zero Invariant Sections. If the Document does not identify 4002 any Invariant Sections then there are none. 4003 4004 The “Cover Texts” are certain short passages of text that are 4005 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 4006 that says that the Document is released under this License. A 4007 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 4008 be at most 25 words. 4009 4010 A “Transparent” copy of the Document means a machine-readable copy, 4011 represented in a format whose specification is available to the 4012 general public, that is suitable for revising the document 4013 straightforwardly with generic text editors or (for images composed 4014 of pixels) generic paint programs or (for drawings) some widely 4015 available drawing editor, and that is suitable for input to text 4016 formatters or for automatic translation to a variety of formats 4017 suitable for input to text formatters. A copy made in an otherwise 4018 Transparent file format whose markup, or absence of markup, has 4019 been arranged to thwart or discourage subsequent modification by 4020 readers is not Transparent. An image format is not Transparent if 4021 used for any substantial amount of text. A copy that is not 4022 “Transparent” is called “Opaque”. 4023 4024 Examples of suitable formats for Transparent copies include plain 4025 ASCII without markup, Texinfo input format, LaTeX input format, 4026 SGML or XML using a publicly available DTD, and standard-conforming 4027 simple HTML, PostScript or PDF designed for human modification. 4028 Examples of transparent image formats include PNG, XCF and JPG. 4029 Opaque formats include proprietary formats that can be read and 4030 edited only by proprietary word processors, SGML or XML for which 4031 the DTD and/or processing tools are not generally available, and 4032 the machine-generated HTML, PostScript or PDF produced by some word 4033 processors for output purposes only. 4034 4035 The “Title Page” means, for a printed book, the title page itself, 4036 plus such following pages as are needed to hold, legibly, the 4037 material this License requires to appear in the title page. For 4038 works in formats which do not have any title page as such, “Title 4039 Page” means the text near the most prominent appearance of the 4040 work’s title, preceding the beginning of the body of the text. 4041 4042 A section “Entitled XYZ” means a named subunit of the Document 4043 whose title either is precisely XYZ or contains XYZ in parentheses 4044 following text that translates XYZ in another language. (Here XYZ 4045 stands for a specific section name mentioned below, such as 4046 “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) 4047 To “Preserve the Title” of such a section when you modify the 4048 Document means that it remains a section “Entitled XYZ” according 4049 to this definition. 4050 4051 The Document may include Warranty Disclaimers next to the notice 4052 which states that this License applies to the Document. These 4053 Warranty Disclaimers are considered to be included by reference in 4054 this License, but only as regards disclaiming warranties: any other 4055 implication that these Warranty Disclaimers may have is void and 4056 has no effect on the meaning of this License. 4057 4058 2. VERBATIM COPYING 4059 4060 You may copy and distribute the Document in any medium, either 4061 commercially or noncommercially, provided that this License, the 4062 copyright notices, and the license notice saying this License 4063 applies to the Document are reproduced in all copies, and that you 4064 add no other conditions whatsoever to those of this License. You 4065 may not use technical measures to obstruct or control the reading 4066 or further copying of the copies you make or distribute. However, 4067 you may accept compensation in exchange for copies. If you 4068 distribute a large enough number of copies you must also follow the 4069 conditions in section 3. 4070 4071 You may also lend copies, under the same conditions stated above, 4072 and you may publicly display copies. 4073 4074 3. COPYING IN QUANTITY 4075 4076 If you publish printed copies (or copies in media that commonly 4077 have printed covers) of the Document, numbering more than 100, and 4078 the Document’s license notice requires Cover Texts, you must 4079 enclose the copies in covers that carry, clearly and legibly, all 4080 these Cover Texts: Front-Cover Texts on the front cover, and 4081 Back-Cover Texts on the back cover. Both covers must also clearly 4082 and legibly identify you as the publisher of these copies. The 4083 front cover must present the full title with all words of the title 4084 equally prominent and visible. You may add other material on the 4085 covers in addition. Copying with changes limited to the covers, as 4086 long as they preserve the title of the Document and satisfy these 4087 conditions, can be treated as verbatim copying in other respects. 4088 4089 If the required texts for either cover are too voluminous to fit 4090 legibly, you should put the first ones listed (as many as fit 4091 reasonably) on the actual cover, and continue the rest onto 4092 adjacent pages. 4093 4094 If you publish or distribute Opaque copies of the Document 4095 numbering more than 100, you must either include a machine-readable 4096 Transparent copy along with each Opaque copy, or state in or with 4097 each Opaque copy a computer-network location from which the general 4098 network-using public has access to download using public-standard 4099 network protocols a complete Transparent copy of the Document, free 4100 of added material. If you use the latter option, you must take 4101 reasonably prudent steps, when you begin distribution of Opaque 4102 copies in quantity, to ensure that this Transparent copy will 4103 remain thus accessible at the stated location until at least one 4104 year after the last time you distribute an Opaque copy (directly or 4105 through your agents or retailers) of that edition to the public. 4106 4107 It is requested, but not required, that you contact the authors of 4108 the Document well before redistributing any large number of copies, 4109 to give them a chance to provide you with an updated version of the 4110 Document. 4111 4112 4. MODIFICATIONS 4113 4114 You may copy and distribute a Modified Version of the Document 4115 under the conditions of sections 2 and 3 above, provided that you 4116 release the Modified Version under precisely this License, with the 4117 Modified Version filling the role of the Document, thus licensing 4118 distribution and modification of the Modified Version to whoever 4119 possesses a copy of it. In addition, you must do these things in 4120 the Modified Version: 4121 4122 A. Use in the Title Page (and on the covers, if any) a title 4123 distinct from that of the Document, and from those of previous 4124 versions (which should, if there were any, be listed in the 4125 History section of the Document). You may use the same title 4126 as a previous version if the original publisher of that 4127 version gives permission. 4128 4129 B. List on the Title Page, as authors, one or more persons or 4130 entities responsible for authorship of the modifications in 4131 the Modified Version, together with at least five of the 4132 principal authors of the Document (all of its principal 4133 authors, if it has fewer than five), unless they release you 4134 from this requirement. 4135 4136 C. State on the Title page the name of the publisher of the 4137 Modified Version, as the publisher. 4138 4139 D. Preserve all the copyright notices of the Document. 4140 4141 E. Add an appropriate copyright notice for your modifications 4142 adjacent to the other copyright notices. 4143 4144 F. Include, immediately after the copyright notices, a license 4145 notice giving the public permission to use the Modified 4146 Version under the terms of this License, in the form shown in 4147 the Addendum below. 4148 4149 G. Preserve in that license notice the full lists of Invariant 4150 Sections and required Cover Texts given in the Document’s 4151 license notice. 4152 4153 H. Include an unaltered copy of this License. 4154 4155 I. Preserve the section Entitled “History”, Preserve its Title, 4156 and add to it an item stating at least the title, year, new 4157 authors, and publisher of the Modified Version as given on the 4158 Title Page. If there is no section Entitled “History” in the 4159 Document, create one stating the title, year, authors, and 4160 publisher of the Document as given on its Title Page, then add 4161 an item describing the Modified Version as stated in the 4162 previous sentence. 4163 4164 J. Preserve the network location, if any, given in the Document 4165 for public access to a Transparent copy of the Document, and 4166 likewise the network locations given in the Document for 4167 previous versions it was based on. These may be placed in the 4168 “History” section. You may omit a network location for a work 4169 that was published at least four years before the Document 4170 itself, or if the original publisher of the version it refers 4171 to gives permission. 4172 4173 K. For any section Entitled “Acknowledgements” or “Dedications”, 4174 Preserve the Title of the section, and preserve in the section 4175 all the substance and tone of each of the contributor 4176 acknowledgements and/or dedications given therein. 4177 4178 L. Preserve all the Invariant Sections of the Document, unaltered 4179 in their text and in their titles. Section numbers or the 4180 equivalent are not considered part of the section titles. 4181 4182 M. Delete any section Entitled “Endorsements”. Such a section 4183 may not be included in the Modified Version. 4184 4185 N. Do not retitle any existing section to be Entitled 4186 “Endorsements” or to conflict in title with any Invariant 4187 Section. 4188 4189 O. Preserve any Warranty Disclaimers. 4190 4191 If the Modified Version includes new front-matter sections or 4192 appendices that qualify as Secondary Sections and contain no 4193 material copied from the Document, you may at your option designate 4194 some or all of these sections as invariant. To do this, add their 4195 titles to the list of Invariant Sections in the Modified Version’s 4196 license notice. These titles must be distinct from any other 4197 section titles. 4198 4199 You may add a section Entitled “Endorsements”, provided it contains 4200 nothing but endorsements of your Modified Version by various 4201 parties—for example, statements of peer review or that the text has 4202 been approved by an organization as the authoritative definition of 4203 a standard. 4204 4205 You may add a passage of up to five words as a Front-Cover Text, 4206 and a passage of up to 25 words as a Back-Cover Text, to the end of 4207 the list of Cover Texts in the Modified Version. Only one passage 4208 of Front-Cover Text and one of Back-Cover Text may be added by (or 4209 through arrangements made by) any one entity. If the Document 4210 already includes a cover text for the same cover, previously added 4211 by you or by arrangement made by the same entity you are acting on 4212 behalf of, you may not add another; but you may replace the old 4213 one, on explicit permission from the previous publisher that added 4214 the old one. 4215 4216 The author(s) and publisher(s) of the Document do not by this 4217 License give permission to use their names for publicity for or to 4218 assert or imply endorsement of any Modified Version. 4219 4220 5. COMBINING DOCUMENTS 4221 4222 You may combine the Document with other documents released under 4223 this License, under the terms defined in section 4 above for 4224 modified versions, provided that you include in the combination all 4225 of the Invariant Sections of all of the original documents, 4226 unmodified, and list them all as Invariant Sections of your 4227 combined work in its license notice, and that you preserve all 4228 their Warranty Disclaimers. 4229 4230 The combined work need only contain one copy of this License, and 4231 multiple identical Invariant Sections may be replaced with a single 4232 copy. If there are multiple Invariant Sections with the same name 4233 but different contents, make the title of each such section unique 4234 by adding at the end of it, in parentheses, the name of the 4235 original author or publisher of that section if known, or else a 4236 unique number. Make the same adjustment to the section titles in 4237 the list of Invariant Sections in the license notice of the 4238 combined work. 4239 4240 In the combination, you must combine any sections Entitled 4241 “History” in the various original documents, forming one section 4242 Entitled “History”; likewise combine any sections Entitled 4243 “Acknowledgements”, and any sections Entitled “Dedications”. You 4244 must delete all sections Entitled “Endorsements.” 4245 4246 6. COLLECTIONS OF DOCUMENTS 4247 4248 You may make a collection consisting of the Document and other 4249 documents released under this License, and replace the individual 4250 copies of this License in the various documents with a single copy 4251 that is included in the collection, provided that you follow the 4252 rules of this License for verbatim copying of each of the documents 4253 in all other respects. 4254 4255 You may extract a single document from such a collection, and 4256 distribute it individually under this License, provided you insert 4257 a copy of this License into the extracted document, and follow this 4258 License in all other respects regarding verbatim copying of that 4259 document. 4260 4261 7. AGGREGATION WITH INDEPENDENT WORKS 4262 4263 A compilation of the Document or its derivatives with other 4264 separate and independent documents or works, in or on a volume of a 4265 storage or distribution medium, is called an “aggregate” if the 4266 copyright resulting from the compilation is not used to limit the 4267 legal rights of the compilation’s users beyond what the individual 4268 works permit. When the Document is included in an aggregate, this 4269 License does not apply to the other works in the aggregate which 4270 are not themselves derivative works of the Document. 4271 4272 If the Cover Text requirement of section 3 is applicable to these 4273 copies of the Document, then if the Document is less than one half 4274 of the entire aggregate, the Document’s Cover Texts may be placed 4275 on covers that bracket the Document within the aggregate, or the 4276 electronic equivalent of covers if the Document is in electronic 4277 form. Otherwise they must appear on printed covers that bracket 4278 the whole aggregate. 4279 4280 8. TRANSLATION 4281 4282 Translation is considered a kind of modification, so you may 4283 distribute translations of the Document under the terms of section 4284 4. Replacing Invariant Sections with translations requires special 4285 permission from their copyright holders, but you may include 4286 translations of some or all Invariant Sections in addition to the 4287 original versions of these Invariant Sections. You may include a 4288 translation of this License, and all the license notices in the 4289 Document, and any Warranty Disclaimers, provided that you also 4290 include the original English version of this License and the 4291 original versions of those notices and disclaimers. In case of a 4292 disagreement between the translation and the original version of 4293 this License or a notice or disclaimer, the original version will 4294 prevail. 4295 4296 If a section in the Document is Entitled “Acknowledgements”, 4297 “Dedications”, or “History”, the requirement (section 4) to 4298 Preserve its Title (section 1) will typically require changing the 4299 actual title. 4300 4301 9. TERMINATION 4302 4303 You may not copy, modify, sublicense, or distribute the Document 4304 except as expressly provided for under this License. Any other 4305 attempt to copy, modify, sublicense or distribute the Document is 4306 void, and will automatically terminate your rights under this 4307 License. However, parties who have received copies, or rights, 4308 from you under this License will not have their licenses terminated 4309 so long as such parties remain in full compliance. 4310 4311 10. FUTURE REVISIONS OF THIS LICENSE 4312 4313 The Free Software Foundation may publish new, revised versions of 4314 the GNU Free Documentation License from time to time. Such new 4315 versions will be similar in spirit to the present version, but may 4316 differ in detail to address new problems or concerns. See 4317 <https://www.gnu.org/copyleft/>. 4318 4319 Each version of the License is given a distinguishing version 4320 number. If the Document specifies that a particular numbered 4321 version of this License “or any later version” applies to it, you 4322 have the option of following the terms and conditions either of 4323 that specified version or of any later version that has been 4324 published (not as a draft) by the Free Software Foundation. If the 4325 Document does not specify a version number of this License, you may 4326 choose any version ever published (not as a draft) by the Free 4327 Software Foundation. 4328 4329A.1 ADDENDUM: How to Use This License For Your Documents 4330======================================================== 4331 4332To use this License in a document you have written, include a copy of 4333the License in the document and put the following copyright and license 4334notices just after the title page: 4335 4336 Copyright (C) YEAR YOUR NAME. 4337 Permission is granted to copy, distribute and/or modify this document 4338 under the terms of the GNU Free Documentation License, Version 1.2 4339 or any later version published by the Free Software Foundation; 4340 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 4341 Texts. A copy of the license is included in the section entitled ``GNU 4342 Free Documentation License''. 4343 4344 If you have Invariant Sections, Front-Cover Texts and Back-Cover 4345Texts, replace the “with...Texts.” line with this: 4346 4347 with the Invariant Sections being LIST THEIR TITLES, with 4348 the Front-Cover Texts being LIST, and with the Back-Cover Texts 4349 being LIST. 4350 4351 If you have Invariant Sections without Cover Texts, or some other 4352combination of the three, merge those two alternatives to suit the 4353situation. 4354 4355 If your document contains nontrivial examples of program code, we 4356recommend releasing these examples in parallel under your choice of free 4357software license, such as the GNU General Public License, to permit 4358their use in free software. 4359 4360 4361File: mpfr.info, Node: Concept Index, Next: Function and Type Index, Prev: GNU Free Documentation License, Up: Top 4362 4363Concept Index 4364************* 4365 4366�[index�] 4367* Menu: 4368 4369* Accuracy: MPFR Interface. (line 25) 4370* Arithmetic functions: Arithmetic Functions. (line 3) 4371* Assignment functions: Assignment Functions. (line 3) 4372* Combined initialization and assignment functions: Combined Initialization and Assignment Functions. 4373 (line 3) 4374* Comparison functions: Comparison Functions. (line 3) 4375* Compatibility with MPF: Compatibility with MPF. 4376 (line 3) 4377* Conditions for copying MPFR: Copying. (line 6) 4378* Conversion functions: Conversion Functions. (line 3) 4379* Copying conditions: Copying. (line 6) 4380* Custom interface: Custom Interface. (line 3) 4381* Exception related functions: Exception Related Functions. 4382 (line 3) 4383* Exponent: Nomenclature and Types. 4384 (line 41) 4385* Floating-point functions: MPFR Interface. (line 6) 4386* Floating-point number: Nomenclature and Types. 4387 (line 6) 4388* GNU Free Documentation License: GNU Free Documentation License. 4389 (line 6) 4390* GNU Free Documentation License <1>: GNU Free Documentation License. 4391 (line 6) 4392* Group of flags: Nomenclature and Types. 4393 (line 52) 4394* I/O functions: Input and Output Functions. 4395 (line 3) 4396* I/O functions <1>: Formatted Output Functions. 4397 (line 3) 4398* Initialization functions: Initialization Functions. 4399 (line 3) 4400* Input functions: Input and Output Functions. 4401 (line 3) 4402* Installation: Installing MPFR. (line 6) 4403* Integer related functions: Integer and Remainder Related Functions. 4404 (line 3) 4405* Internals: Internals. (line 3) 4406* intmax_t: Headers and Libraries. 4407 (line 22) 4408* inttypes.h: Headers and Libraries. 4409 (line 22) 4410* libmpfr: Headers and Libraries. 4411 (line 50) 4412* Libraries: Headers and Libraries. 4413 (line 50) 4414* Libtool: Headers and Libraries. 4415 (line 56) 4416* Limb: Internals. (line 6) 4417* Linking: Headers and Libraries. 4418 (line 50) 4419* Memory handling functions: Memory Handling Functions. 4420 (line 3) 4421* Miscellaneous float functions: Miscellaneous Functions. 4422 (line 3) 4423* mpfr.h: Headers and Libraries. 4424 (line 6) 4425* Output functions: Input and Output Functions. 4426 (line 3) 4427* Output functions <1>: Formatted Output Functions. 4428 (line 3) 4429* Precision: Nomenclature and Types. 4430 (line 27) 4431* Precision <1>: MPFR Interface. (line 17) 4432* Regular number: Nomenclature and Types. 4433 (line 6) 4434* Remainder related functions: Integer and Remainder Related Functions. 4435 (line 3) 4436* Reporting bugs: Reporting Bugs. (line 6) 4437* Rounding: Nomenclature and Types. 4438 (line 47) 4439* Rounding mode related functions: Rounding-Related Functions. 4440 (line 3) 4441* stdarg.h: Headers and Libraries. 4442 (line 19) 4443* stdint.h: Headers and Libraries. 4444 (line 22) 4445* stdio.h: Headers and Libraries. 4446 (line 12) 4447* Ternary value: Rounding. (line 79) 4448* Transcendental functions: Transcendental Functions. 4449 (line 3) 4450* uintmax_t: Headers and Libraries. 4451 (line 22) 4452 4453 4454File: mpfr.info, Node: Function and Type Index, Prev: Concept Index, Up: Top 4455 4456Function and Type Index 4457*********************** 4458 4459�[index�] 4460* Menu: 4461 4462* mpfr_abs: Arithmetic Functions. 4463 (line 144) 4464* mpfr_acos: Transcendental Functions. 4465 (line 120) 4466* mpfr_acosh: Transcendental Functions. 4467 (line 185) 4468* mpfr_add: Arithmetic Functions. 4469 (line 6) 4470* mpfr_add_d: Arithmetic Functions. 4471 (line 12) 4472* mpfr_add_q: Arithmetic Functions. 4473 (line 16) 4474* mpfr_add_si: Arithmetic Functions. 4475 (line 10) 4476* mpfr_add_ui: Arithmetic Functions. 4477 (line 8) 4478* mpfr_add_z: Arithmetic Functions. 4479 (line 14) 4480* mpfr_agm: Transcendental Functions. 4481 (line 281) 4482* mpfr_ai: Transcendental Functions. 4483 (line 291) 4484* mpfr_asin: Transcendental Functions. 4485 (line 121) 4486* mpfr_asinh: Transcendental Functions. 4487 (line 186) 4488* mpfr_asprintf: Formatted Output Functions. 4489 (line 199) 4490* mpfr_atan: Transcendental Functions. 4491 (line 122) 4492* mpfr_atan2: Transcendental Functions. 4493 (line 132) 4494* mpfr_atanh: Transcendental Functions. 4495 (line 187) 4496* mpfr_beta: Transcendental Functions. 4497 (line 243) 4498* mpfr_buildopt_decimal_p: Miscellaneous Functions. 4499 (line 185) 4500* mpfr_buildopt_float128_p: Miscellaneous Functions. 4501 (line 180) 4502* mpfr_buildopt_gmpinternals_p: Miscellaneous Functions. 4503 (line 190) 4504* mpfr_buildopt_sharedcache_p: Miscellaneous Functions. 4505 (line 195) 4506* mpfr_buildopt_tls_p: Miscellaneous Functions. 4507 (line 174) 4508* mpfr_buildopt_tune_case: Miscellaneous Functions. 4509 (line 203) 4510* mpfr_can_round: Rounding-Related Functions. 4511 (line 40) 4512* mpfr_cbrt: Arithmetic Functions. 4513 (line 116) 4514* mpfr_ceil: Integer and Remainder Related Functions. 4515 (line 7) 4516* mpfr_check_range: Exception Related Functions. 4517 (line 50) 4518* mpfr_clear: Initialization Functions. 4519 (line 33) 4520* mpfr_clears: Initialization Functions. 4521 (line 38) 4522* mpfr_clear_divby0: Exception Related Functions. 4523 (line 153) 4524* mpfr_clear_erangeflag: Exception Related Functions. 4525 (line 156) 4526* mpfr_clear_flags: Exception Related Functions. 4527 (line 160) 4528* mpfr_clear_inexflag: Exception Related Functions. 4529 (line 155) 4530* mpfr_clear_nanflag: Exception Related Functions. 4531 (line 154) 4532* mpfr_clear_overflow: Exception Related Functions. 4533 (line 152) 4534* mpfr_clear_underflow: Exception Related Functions. 4535 (line 151) 4536* mpfr_cmp: Comparison Functions. 4537 (line 6) 4538* mpfr_cmpabs: Comparison Functions. 4539 (line 34) 4540* mpfr_cmpabs_ui: Comparison Functions. 4541 (line 35) 4542* mpfr_cmp_d: Comparison Functions. 4543 (line 9) 4544* mpfr_cmp_f: Comparison Functions. 4545 (line 13) 4546* mpfr_cmp_ld: Comparison Functions. 4547 (line 10) 4548* mpfr_cmp_q: Comparison Functions. 4549 (line 12) 4550* mpfr_cmp_si: Comparison Functions. 4551 (line 8) 4552* mpfr_cmp_si_2exp: Comparison Functions. 4553 (line 29) 4554* mpfr_cmp_ui: Comparison Functions. 4555 (line 7) 4556* mpfr_cmp_ui_2exp: Comparison Functions. 4557 (line 27) 4558* mpfr_cmp_z: Comparison Functions. 4559 (line 11) 4560* mpfr_const_catalan: Transcendental Functions. 4561 (line 302) 4562* mpfr_const_euler: Transcendental Functions. 4563 (line 301) 4564* mpfr_const_log2: Transcendental Functions. 4565 (line 299) 4566* mpfr_const_pi: Transcendental Functions. 4567 (line 300) 4568* mpfr_copysign: Miscellaneous Functions. 4569 (line 127) 4570* mpfr_cos: Transcendental Functions. 4571 (line 98) 4572* mpfr_cosh: Transcendental Functions. 4573 (line 165) 4574* mpfr_cot: Transcendental Functions. 4575 (line 116) 4576* mpfr_coth: Transcendental Functions. 4577 (line 181) 4578* mpfr_csc: Transcendental Functions. 4579 (line 115) 4580* mpfr_csch: Transcendental Functions. 4581 (line 180) 4582* mpfr_custom_get_exp: Custom Interface. (line 76) 4583* mpfr_custom_get_kind: Custom Interface. (line 66) 4584* mpfr_custom_get_significand: Custom Interface. (line 71) 4585* mpfr_custom_get_size: Custom Interface. (line 37) 4586* mpfr_custom_init: Custom Interface. (line 41) 4587* mpfr_custom_init_set: Custom Interface. (line 48) 4588* mpfr_custom_move: Custom Interface. (line 85) 4589* MPFR_DECL_INIT: Initialization Functions. 4590 (line 77) 4591* mpfr_digamma: Transcendental Functions. 4592 (line 238) 4593* mpfr_dim: Arithmetic Functions. 4594 (line 156) 4595* mpfr_div: Arithmetic Functions. 4596 (line 74) 4597* mpfr_divby0_p: Exception Related Functions. 4598 (line 176) 4599* mpfr_div_2exp: Compatibility with MPF. 4600 (line 56) 4601* mpfr_div_2si: Arithmetic Functions. 4602 (line 171) 4603* mpfr_div_2ui: Arithmetic Functions. 4604 (line 169) 4605* mpfr_div_d: Arithmetic Functions. 4606 (line 86) 4607* mpfr_div_q: Arithmetic Functions. 4608 (line 90) 4609* mpfr_div_si: Arithmetic Functions. 4610 (line 82) 4611* mpfr_div_ui: Arithmetic Functions. 4612 (line 78) 4613* mpfr_div_z: Arithmetic Functions. 4614 (line 88) 4615* mpfr_dot: Arithmetic Functions. 4616 (line 228) 4617* mpfr_dump: Input and Output Functions. 4618 (line 76) 4619* mpfr_d_div: Arithmetic Functions. 4620 (line 84) 4621* mpfr_d_sub: Arithmetic Functions. 4622 (line 36) 4623* mpfr_eint: Transcendental Functions. 4624 (line 191) 4625* mpfr_eq: Compatibility with MPF. 4626 (line 35) 4627* mpfr_equal_p: Comparison Functions. 4628 (line 60) 4629* mpfr_erandom: Miscellaneous Functions. 4630 (line 99) 4631* mpfr_erangeflag_p: Exception Related Functions. 4632 (line 179) 4633* mpfr_erf: Transcendental Functions. 4634 (line 255) 4635* mpfr_erfc: Transcendental Functions. 4636 (line 256) 4637* mpfr_exp: Transcendental Functions. 4638 (line 41) 4639* mpfr_exp10: Transcendental Functions. 4640 (line 43) 4641* mpfr_exp2: Transcendental Functions. 4642 (line 42) 4643* mpfr_expm1: Transcendental Functions. 4644 (line 47) 4645* mpfr_exp_t: Nomenclature and Types. 4646 (line 41) 4647* mpfr_fac_ui: Arithmetic Functions. 4648 (line 177) 4649* mpfr_fits_intmax_p: Conversion Functions. 4650 (line 185) 4651* mpfr_fits_sint_p: Conversion Functions. 4652 (line 181) 4653* mpfr_fits_slong_p: Conversion Functions. 4654 (line 179) 4655* mpfr_fits_sshort_p: Conversion Functions. 4656 (line 183) 4657* mpfr_fits_uintmax_p: Conversion Functions. 4658 (line 184) 4659* mpfr_fits_uint_p: Conversion Functions. 4660 (line 180) 4661* mpfr_fits_ulong_p: Conversion Functions. 4662 (line 178) 4663* mpfr_fits_ushort_p: Conversion Functions. 4664 (line 182) 4665* mpfr_flags_clear: Exception Related Functions. 4666 (line 190) 4667* mpfr_flags_restore: Exception Related Functions. 4668 (line 214) 4669* mpfr_flags_save: Exception Related Functions. 4670 (line 210) 4671* mpfr_flags_set: Exception Related Functions. 4672 (line 193) 4673* mpfr_flags_t: Nomenclature and Types. 4674 (line 52) 4675* mpfr_flags_test: Exception Related Functions. 4676 (line 196) 4677* mpfr_floor: Integer and Remainder Related Functions. 4678 (line 8) 4679* mpfr_fma: Arithmetic Functions. 4680 (line 181) 4681* mpfr_fmma: Arithmetic Functions. 4682 (line 191) 4683* mpfr_fmms: Arithmetic Functions. 4684 (line 193) 4685* mpfr_fmod: Integer and Remainder Related Functions. 4686 (line 108) 4687* mpfr_fmodquo: Integer and Remainder Related Functions. 4688 (line 110) 4689* mpfr_fms: Arithmetic Functions. 4690 (line 183) 4691* mpfr_fpif_export: Input and Output Functions. 4692 (line 51) 4693* mpfr_fpif_import: Input and Output Functions. 4694 (line 62) 4695* mpfr_fprintf: Formatted Output Functions. 4696 (line 163) 4697* mpfr_frac: Integer and Remainder Related Functions. 4698 (line 91) 4699* mpfr_free_cache: Memory Handling Functions. 4700 (line 9) 4701* mpfr_free_cache2: Memory Handling Functions. 4702 (line 16) 4703* mpfr_free_pool: Memory Handling Functions. 4704 (line 30) 4705* mpfr_free_str: Conversion Functions. 4706 (line 173) 4707* mpfr_frexp: Conversion Functions. 4708 (line 52) 4709* mpfr_gamma: Transcendental Functions. 4710 (line 206) 4711* mpfr_gamma_inc: Transcendental Functions. 4712 (line 207) 4713* mpfr_get_d: Conversion Functions. 4714 (line 7) 4715* mpfr_get_decimal128: Conversion Functions. 4716 (line 11) 4717* mpfr_get_decimal64: Conversion Functions. 4718 (line 10) 4719* mpfr_get_default_prec: Initialization Functions. 4720 (line 115) 4721* mpfr_get_default_rounding_mode: Rounding-Related Functions. 4722 (line 10) 4723* mpfr_get_d_2exp: Conversion Functions. 4724 (line 39) 4725* mpfr_get_emax: Exception Related Functions. 4726 (line 7) 4727* mpfr_get_emax_max: Exception Related Functions. 4728 (line 43) 4729* mpfr_get_emax_min: Exception Related Functions. 4730 (line 42) 4731* mpfr_get_emin: Exception Related Functions. 4732 (line 6) 4733* mpfr_get_emin_max: Exception Related Functions. 4734 (line 41) 4735* mpfr_get_emin_min: Exception Related Functions. 4736 (line 40) 4737* mpfr_get_exp: Miscellaneous Functions. 4738 (line 105) 4739* mpfr_get_f: Conversion Functions. 4740 (line 88) 4741* mpfr_get_float128: Conversion Functions. 4742 (line 9) 4743* mpfr_get_flt: Conversion Functions. 4744 (line 6) 4745* mpfr_get_ld: Conversion Functions. 4746 (line 8) 4747* mpfr_get_ld_2exp: Conversion Functions. 4748 (line 41) 4749* mpfr_get_patches: Miscellaneous Functions. 4750 (line 165) 4751* mpfr_get_prec: Initialization Functions. 4752 (line 152) 4753* mpfr_get_q: Conversion Functions. 4754 (line 83) 4755* mpfr_get_si: Conversion Functions. 4756 (line 24) 4757* mpfr_get_sj: Conversion Functions. 4758 (line 26) 4759* mpfr_get_str: Conversion Functions. 4760 (line 113) 4761* mpfr_get_str_ndigits: Conversion Functions. 4762 (line 101) 4763* mpfr_get_ui: Conversion Functions. 4764 (line 25) 4765* mpfr_get_uj: Conversion Functions. 4766 (line 27) 4767* mpfr_get_version: Miscellaneous Functions. 4768 (line 134) 4769* mpfr_get_z: Conversion Functions. 4770 (line 74) 4771* mpfr_get_z_2exp: Conversion Functions. 4772 (line 61) 4773* mpfr_grandom: Miscellaneous Functions. 4774 (line 69) 4775* mpfr_greaterequal_p: Comparison Functions. 4776 (line 57) 4777* mpfr_greater_p: Comparison Functions. 4778 (line 56) 4779* mpfr_hypot: Arithmetic Functions. 4780 (line 201) 4781* mpfr_inexflag_p: Exception Related Functions. 4782 (line 178) 4783* mpfr_inf_p: Comparison Functions. 4784 (line 41) 4785* mpfr_init: Initialization Functions. 4786 (line 56) 4787* mpfr_init2: Initialization Functions. 4788 (line 10) 4789* mpfr_inits: Initialization Functions. 4790 (line 65) 4791* mpfr_inits2: Initialization Functions. 4792 (line 25) 4793* mpfr_init_set: Combined Initialization and Assignment Functions. 4794 (line 6) 4795* mpfr_init_set_d: Combined Initialization and Assignment Functions. 4796 (line 11) 4797* mpfr_init_set_f: Combined Initialization and Assignment Functions. 4798 (line 16) 4799* mpfr_init_set_ld: Combined Initialization and Assignment Functions. 4800 (line 12) 4801* mpfr_init_set_q: Combined Initialization and Assignment Functions. 4802 (line 15) 4803* mpfr_init_set_si: Combined Initialization and Assignment Functions. 4804 (line 9) 4805* mpfr_init_set_str: Combined Initialization and Assignment Functions. 4806 (line 21) 4807* mpfr_init_set_ui: Combined Initialization and Assignment Functions. 4808 (line 7) 4809* mpfr_init_set_z: Combined Initialization and Assignment Functions. 4810 (line 14) 4811* mpfr_inp_str: Input and Output Functions. 4812 (line 39) 4813* mpfr_integer_p: Integer and Remainder Related Functions. 4814 (line 137) 4815* mpfr_j0: Transcendental Functions. 4816 (line 260) 4817* mpfr_j1: Transcendental Functions. 4818 (line 261) 4819* mpfr_jn: Transcendental Functions. 4820 (line 262) 4821* mpfr_lessequal_p: Comparison Functions. 4822 (line 59) 4823* mpfr_lessgreater_p: Comparison Functions. 4824 (line 65) 4825* mpfr_less_p: Comparison Functions. 4826 (line 58) 4827* mpfr_lgamma: Transcendental Functions. 4828 (line 228) 4829* mpfr_li2: Transcendental Functions. 4830 (line 201) 4831* mpfr_lngamma: Transcendental Functions. 4832 (line 220) 4833* mpfr_log: Transcendental Functions. 4834 (line 25) 4835* mpfr_log10: Transcendental Functions. 4836 (line 29) 4837* mpfr_log1p: Transcendental Functions. 4838 (line 37) 4839* mpfr_log2: Transcendental Functions. 4840 (line 28) 4841* mpfr_log_ui: Transcendental Functions. 4842 (line 26) 4843* mpfr_max: Miscellaneous Functions. 4844 (line 22) 4845* mpfr_min: Miscellaneous Functions. 4846 (line 20) 4847* mpfr_min_prec: Rounding-Related Functions. 4848 (line 85) 4849* mpfr_modf: Integer and Remainder Related Functions. 4850 (line 98) 4851* mpfr_mp_memory_cleanup: Memory Handling Functions. 4852 (line 35) 4853* mpfr_mul: Arithmetic Functions. 4854 (line 53) 4855* mpfr_mul_2exp: Compatibility with MPF. 4856 (line 54) 4857* mpfr_mul_2si: Arithmetic Functions. 4858 (line 164) 4859* mpfr_mul_2ui: Arithmetic Functions. 4860 (line 162) 4861* mpfr_mul_d: Arithmetic Functions. 4862 (line 59) 4863* mpfr_mul_q: Arithmetic Functions. 4864 (line 63) 4865* mpfr_mul_si: Arithmetic Functions. 4866 (line 57) 4867* mpfr_mul_ui: Arithmetic Functions. 4868 (line 55) 4869* mpfr_mul_z: Arithmetic Functions. 4870 (line 61) 4871* mpfr_nanflag_p: Exception Related Functions. 4872 (line 177) 4873* mpfr_nan_p: Comparison Functions. 4874 (line 40) 4875* mpfr_neg: Arithmetic Functions. 4876 (line 143) 4877* mpfr_nextabove: Miscellaneous Functions. 4878 (line 15) 4879* mpfr_nextbelow: Miscellaneous Functions. 4880 (line 16) 4881* mpfr_nexttoward: Miscellaneous Functions. 4882 (line 6) 4883* mpfr_nrandom: Miscellaneous Functions. 4884 (line 67) 4885* mpfr_number_p: Comparison Functions. 4886 (line 42) 4887* mpfr_out_str: Input and Output Functions. 4888 (line 15) 4889* mpfr_overflow_p: Exception Related Functions. 4890 (line 175) 4891* mpfr_pow: Transcendental Functions. 4892 (line 51) 4893* mpfr_pow_si: Transcendental Functions. 4894 (line 55) 4895* mpfr_pow_ui: Transcendental Functions. 4896 (line 53) 4897* mpfr_pow_z: Transcendental Functions. 4898 (line 57) 4899* mpfr_prec_round: Rounding-Related Functions. 4900 (line 13) 4901* mpfr_prec_t: Nomenclature and Types. 4902 (line 27) 4903* mpfr_printf: Formatted Output Functions. 4904 (line 170) 4905* mpfr_print_rnd_mode: Rounding-Related Functions. 4906 (line 89) 4907* mpfr_ptr: Nomenclature and Types. 4908 (line 6) 4909* mpfr_rec_sqrt: Arithmetic Functions. 4910 (line 107) 4911* mpfr_regular_p: Comparison Functions. 4912 (line 44) 4913* mpfr_reldiff: Compatibility with MPF. 4914 (line 46) 4915* mpfr_remainder: Integer and Remainder Related Functions. 4916 (line 112) 4917* mpfr_remquo: Integer and Remainder Related Functions. 4918 (line 114) 4919* mpfr_rint: Integer and Remainder Related Functions. 4920 (line 6) 4921* mpfr_rint_ceil: Integer and Remainder Related Functions. 4922 (line 54) 4923* mpfr_rint_floor: Integer and Remainder Related Functions. 4924 (line 55) 4925* mpfr_rint_round: Integer and Remainder Related Functions. 4926 (line 57) 4927* mpfr_rint_roundeven: Integer and Remainder Related Functions. 4928 (line 59) 4929* mpfr_rint_trunc: Integer and Remainder Related Functions. 4930 (line 61) 4931* mpfr_rnd_t: Nomenclature and Types. 4932 (line 47) 4933* mpfr_root: Arithmetic Functions. 4934 (line 132) 4935* mpfr_rootn_ui: Arithmetic Functions. 4936 (line 117) 4937* mpfr_round: Integer and Remainder Related Functions. 4938 (line 9) 4939* mpfr_roundeven: Integer and Remainder Related Functions. 4940 (line 10) 4941* mpfr_round_nearest_away: Rounding-Related Functions. 4942 (line 95) 4943* mpfr_sec: Transcendental Functions. 4944 (line 114) 4945* mpfr_sech: Transcendental Functions. 4946 (line 179) 4947* mpfr_set: Assignment Functions. 4948 (line 9) 4949* mpfr_setsign: Miscellaneous Functions. 4950 (line 121) 4951* mpfr_set_d: Assignment Functions. 4952 (line 16) 4953* mpfr_set_decimal128: Assignment Functions. 4954 (line 23) 4955* mpfr_set_decimal64: Assignment Functions. 4956 (line 21) 4957* mpfr_set_default_prec: Initialization Functions. 4958 (line 103) 4959* mpfr_set_default_rounding_mode: Rounding-Related Functions. 4960 (line 6) 4961* mpfr_set_divby0: Exception Related Functions. 4962 (line 167) 4963* mpfr_set_emax: Exception Related Functions. 4964 (line 16) 4965* mpfr_set_emin: Exception Related Functions. 4966 (line 15) 4967* mpfr_set_erangeflag: Exception Related Functions. 4968 (line 170) 4969* mpfr_set_exp: Miscellaneous Functions. 4970 (line 112) 4971* mpfr_set_f: Assignment Functions. 4972 (line 27) 4973* mpfr_set_float128: Assignment Functions. 4974 (line 19) 4975* mpfr_set_flt: Assignment Functions. 4976 (line 15) 4977* mpfr_set_inexflag: Exception Related Functions. 4978 (line 169) 4979* mpfr_set_inf: Assignment Functions. 4980 (line 157) 4981* mpfr_set_ld: Assignment Functions. 4982 (line 17) 4983* mpfr_set_nan: Assignment Functions. 4984 (line 156) 4985* mpfr_set_nanflag: Exception Related Functions. 4986 (line 168) 4987* mpfr_set_overflow: Exception Related Functions. 4988 (line 166) 4989* mpfr_set_prec: Initialization Functions. 4990 (line 138) 4991* mpfr_set_prec_raw: Compatibility with MPF. 4992 (line 29) 4993* mpfr_set_q: Assignment Functions. 4994 (line 26) 4995* mpfr_set_si: Assignment Functions. 4996 (line 12) 4997* mpfr_set_si_2exp: Assignment Functions. 4998 (line 64) 4999* mpfr_set_sj: Assignment Functions. 5000 (line 14) 5001* mpfr_set_sj_2exp: Assignment Functions. 5002 (line 68) 5003* mpfr_set_str: Assignment Functions. 5004 (line 76) 5005* mpfr_set_ui: Assignment Functions. 5006 (line 10) 5007* mpfr_set_ui_2exp: Assignment Functions. 5008 (line 62) 5009* mpfr_set_uj: Assignment Functions. 5010 (line 13) 5011* mpfr_set_uj_2exp: Assignment Functions. 5012 (line 66) 5013* mpfr_set_underflow: Exception Related Functions. 5014 (line 165) 5015* mpfr_set_z: Assignment Functions. 5016 (line 25) 5017* mpfr_set_zero: Assignment Functions. 5018 (line 158) 5019* mpfr_set_z_2exp: Assignment Functions. 5020 (line 70) 5021* mpfr_sgn: Comparison Functions. 5022 (line 50) 5023* mpfr_signbit: Miscellaneous Functions. 5024 (line 117) 5025* mpfr_sin: Transcendental Functions. 5026 (line 99) 5027* mpfr_sinh: Transcendental Functions. 5028 (line 166) 5029* mpfr_sinh_cosh: Transcendental Functions. 5030 (line 171) 5031* mpfr_sin_cos: Transcendental Functions. 5032 (line 104) 5033* mpfr_si_div: Arithmetic Functions. 5034 (line 80) 5035* mpfr_si_sub: Arithmetic Functions. 5036 (line 32) 5037* mpfr_snprintf: Formatted Output Functions. 5038 (line 186) 5039* mpfr_sprintf: Formatted Output Functions. 5040 (line 176) 5041* mpfr_sqr: Arithmetic Functions. 5042 (line 71) 5043* mpfr_sqrt: Arithmetic Functions. 5044 (line 100) 5045* mpfr_sqrt_ui: Arithmetic Functions. 5046 (line 101) 5047* mpfr_strtofr: Assignment Functions. 5048 (line 94) 5049* mpfr_sub: Arithmetic Functions. 5050 (line 26) 5051* mpfr_subnormalize: Exception Related Functions. 5052 (line 73) 5053* mpfr_sub_d: Arithmetic Functions. 5054 (line 38) 5055* mpfr_sub_q: Arithmetic Functions. 5056 (line 44) 5057* mpfr_sub_si: Arithmetic Functions. 5058 (line 34) 5059* mpfr_sub_ui: Arithmetic Functions. 5060 (line 30) 5061* mpfr_sub_z: Arithmetic Functions. 5062 (line 42) 5063* mpfr_sum: Arithmetic Functions. 5064 (line 211) 5065* mpfr_swap: Assignment Functions. 5066 (line 164) 5067* mpfr_t: Nomenclature and Types. 5068 (line 6) 5069* mpfr_tan: Transcendental Functions. 5070 (line 100) 5071* mpfr_tanh: Transcendental Functions. 5072 (line 167) 5073* mpfr_total_order_p: Comparison Functions. 5074 (line 74) 5075* mpfr_trunc: Integer and Remainder Related Functions. 5076 (line 11) 5077* mpfr_ui_div: Arithmetic Functions. 5078 (line 76) 5079* mpfr_ui_pow: Transcendental Functions. 5080 (line 61) 5081* mpfr_ui_pow_ui: Transcendental Functions. 5082 (line 59) 5083* mpfr_ui_sub: Arithmetic Functions. 5084 (line 28) 5085* mpfr_underflow_p: Exception Related Functions. 5086 (line 174) 5087* mpfr_unordered_p: Comparison Functions. 5088 (line 70) 5089* mpfr_urandom: Miscellaneous Functions. 5090 (line 48) 5091* mpfr_urandomb: Miscellaneous Functions. 5092 (line 29) 5093* mpfr_vasprintf: Formatted Output Functions. 5094 (line 200) 5095* MPFR_VERSION: Miscellaneous Functions. 5096 (line 137) 5097* MPFR_VERSION_MAJOR: Miscellaneous Functions. 5098 (line 138) 5099* MPFR_VERSION_MINOR: Miscellaneous Functions. 5100 (line 139) 5101* MPFR_VERSION_NUM: Miscellaneous Functions. 5102 (line 157) 5103* MPFR_VERSION_PATCHLEVEL: Miscellaneous Functions. 5104 (line 140) 5105* MPFR_VERSION_STRING: Miscellaneous Functions. 5106 (line 141) 5107* mpfr_vfprintf: Formatted Output Functions. 5108 (line 164) 5109* mpfr_vprintf: Formatted Output Functions. 5110 (line 171) 5111* mpfr_vsnprintf: Formatted Output Functions. 5112 (line 188) 5113* mpfr_vsprintf: Formatted Output Functions. 5114 (line 177) 5115* mpfr_y0: Transcendental Functions. 5116 (line 271) 5117* mpfr_y1: Transcendental Functions. 5118 (line 272) 5119* mpfr_yn: Transcendental Functions. 5120 (line 273) 5121* mpfr_zero_p: Comparison Functions. 5122 (line 43) 5123* mpfr_zeta: Transcendental Functions. 5124 (line 249) 5125* mpfr_zeta_ui: Transcendental Functions. 5126 (line 250) 5127* mpfr_z_sub: Arithmetic Functions. 5128 (line 40) 5129 5130 5131 5132Tag Table: 5133Node: Top775 5134Node: Copying2042 5135Node: Introduction to MPFR3805 5136Node: Installing MPFR6208 5137Node: Reporting Bugs11668 5138Node: MPFR Basics13700 5139Node: Headers and Libraries14054 5140Node: Nomenclature and Types17650 5141Node: MPFR Variable Conventions20588 5142Node: Rounding22124 5143Ref: ternary value25941 5144Node: Floating-Point Values on Special Numbers27932 5145Node: Exceptions31181 5146Node: Memory Handling35009 5147Node: Getting the Best Efficiency Out of MPFR38760 5148Node: MPFR Interface39672 5149Node: Initialization Functions41989 5150Node: Assignment Functions49518 5151Node: Combined Initialization and Assignment Functions59660 5152Node: Conversion Functions60961 5153Ref: mpfr_get_str_ndigits66837 5154Ref: mpfr_get_str67460 5155Node: Arithmetic Functions72417 5156Node: Comparison Functions84490 5157Node: Transcendental Functions88781 5158Ref: mpfr_pow91426 5159Node: Input and Output Functions105400 5160Node: Formatted Output Functions110698 5161Node: Integer and Remainder Related Functions121040 5162Node: Rounding-Related Functions128568 5163Node: Miscellaneous Functions135170 5164Node: Exception Related Functions145661 5165Node: Memory Handling Functions155904 5166Node: Compatibility with MPF157792 5167Node: Custom Interface160961 5168Node: Internals165592 5169Node: API Compatibility167136 5170Node: Type and Macro Changes169084 5171Node: Added Functions172267 5172Node: Changed Functions177074 5173Node: Removed Functions184433 5174Node: Other Changes185163 5175Node: MPFR and the IEEE 754 Standard186864 5176Node: Contributors189481 5177Node: References192620 5178Node: GNU Free Documentation License194501 5179Node: Concept Index217095 5180Node: Function and Type Index223168 5181 5182End Tag Table 5183 5184 5185Local Variables: 5186coding: utf-8 5187End: 5188