1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename mpfr.info 4@documentencoding UTF-8 5@set VERSION 3.0.1 6@set UPDATED-MONTH April 2011 7@settitle GNU MPFR @value{VERSION} 8@synindex tp fn 9@iftex 10@afourpaper 11@end iftex 12@comment %**end of header 13 14@c Note: avoid using non-ASCII characters directly when possible, 15@c as the "info" utility cannot currently handle them. 16@c http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=212549 17 18@copying 19This manual documents how to install and use the Multiple Precision 20Floating-Point Reliable Library, version @value{VERSION}. 21 22Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. 23 24Permission is granted to copy, distribute and/or modify this document under 25the terms of the GNU Free Documentation License, Version 1.2 or any later 26version published by the Free Software Foundation; with no Invariant Sections, 27with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the 28license is included in @ref{GNU Free Documentation License}. 29@end copying 30 31 32@c Texinfo version 4.2 or up will be needed to process this file. 33@c 34@c A suitable texinfo.tex is supplied, a newer one should work 35@c equally well. 36@c 37@c The edition number is in the VERSION variable above and should be 38@c updated where appropriate. Also, update the month and year in 39@c UPDATED-MONTH. 40 41 42@dircategory Software libraries 43@direntry 44* mpfr: (mpfr). Multiple Precision Floating-Point Reliable Library. 45@end direntry 46 47@c html <meta name=description content="..."> 48@documentdescription 49How to install and use GNU MPFR, a library for reliable multiple precision 50floating-point arithmetic, version @value{VERSION}. 51@end documentdescription 52 53@c smallbook 54@finalout 55@setchapternewpage on 56 57@ifnottex 58@node Top, Copying, (dir), (dir) 59@top GNU MPFR 60@end ifnottex 61 62@iftex 63@titlepage 64@title GNU MPFR 65@subtitle The Multiple Precision Floating-Point Reliable Library 66@subtitle Edition @value{VERSION} 67@subtitle @value{UPDATED-MONTH} 68 69@author The MPFR team 70@email{mpfr@@loria.fr} 71 72@c Include the Distribution inside the titlepage so 73@c that headings are turned off. 74 75@tex 76\global\parindent=0pt 77\global\parskip=8pt 78\global\baselineskip=13pt 79@end tex 80 81@page 82@vskip 0pt plus 1filll 83@end iftex 84 85@insertcopying 86@ifnottex 87@sp 1 88@end ifnottex 89 90@iftex 91@end titlepage 92@headings double 93@end iftex 94 95@c Don't bother with contents for html, the menus seem adequate. 96@ifnothtml 97@contents 98@end ifnothtml 99 100@menu 101* Copying:: MPFR Copying Conditions (LGPL). 102* Introduction to MPFR:: Brief introduction to GNU MPFR. 103* Installing MPFR:: How to configure and compile the MPFR library. 104* Reporting Bugs:: How to usefully report bugs. 105* MPFR Basics:: What every MPFR user should now. 106* MPFR Interface:: MPFR functions and macros. 107* API Compatibility:: API compatibility with previous MPFR versions. 108* Contributors:: 109* References:: 110* GNU Free Documentation License:: 111* Concept Index:: 112* Function Index:: 113@end menu 114 115 116@c @m{T,N} is $T$ in tex or @math{N} otherwise. This is an easy way to give 117@c different forms for math in tex and info. Commas in N or T don't work, 118@c but @C{} can be used instead. \, works in info but not in tex. 119@iftex 120@macro m {T,N} 121@tex$\T\$@end tex 122@end macro 123@end iftex 124@ifnottex 125@macro m {T,N} 126@math{\N\} 127@end macro 128@end ifnottex 129 130@c Usage: @GMPabs{x} 131@c Give either |x| in tex, or abs(x) in info or html. 132@tex 133\gdef\GMPabs#1{|#1|} 134@end tex 135@ifnottex 136@macro GMPabs {X} 137@abs{}(\X\) 138@end macro 139@end ifnottex 140 141@c Usage: @GMPtimes{} 142@c Give either \times or the word "times". 143@tex 144\gdef\GMPtimes{\times} 145@end tex 146@ifnottex 147@macro GMPtimes 148times 149@end macro 150@end ifnottex 151 152@c New math operators. 153@c @abs{} can be used in both tex and info, or just \abs in tex. 154@tex 155\gdef\abs{\mathop{\rm abs}} 156@end tex 157@ifnottex 158@macro abs 159abs 160@end macro 161@end ifnottex 162 163@c @times{} made available as a "*" in info and html (already works in tex). 164@ifnottex 165@macro times 166* 167@end macro 168@end ifnottex 169 170@c Math operators already available in tex, made available in info too. 171@c For example @log{} can be used in both tex and info. 172@ifnottex 173@macro le 174<= 175@end macro 176@macro ge 177>= 178@end macro 179@macro ne 180<> 181@end macro 182@macro log 183log 184@end macro 185@end ifnottex 186 187@c @pom{} definition 188@tex 189\gdef\pom{\ifmmode\pm\else$\pm$\fi} 190@end tex 191@ifnottex 192@macro pom 193± 194@end macro 195@end ifnottex 196 197@c The following macro have been copied from gmp.texi 198@c 199@c Usage: @MPFRpxreftop{info,title} 200@c 201@c Like @pxref{}, but designed for a reference to the top of a document, not 202@c a particular section. 203@c 204@c The texinfo manual recommends putting a likely section name in references 205@c like this, eg. "Introduction", but it seems better to just give the title. 206@c 207@iftex 208@macro MPFRpxreftop{info,title} 209see @cite{\title\}. 210@end macro 211@end iftex 212@ifhtml 213@macro MPFRpxreftop{info,title} 214see @cite{\title\}. 215@end macro 216@end ifhtml 217@ifnottex 218@ifnothtml 219@macro MPFRpxreftop{info,title} 220@pxref{Top,\title\,\title\,\info\,\title\} 221@end macro 222@end ifnothtml 223@end ifnottex 224 225@node Copying, Introduction to MPFR, Top, Top 226@comment node-name, next, previous, up 227@unnumbered MPFR Copying Conditions 228@cindex Copying conditions 229@cindex Conditions for copying MPFR 230 231The GNU MPFR library (or MPFR for short) 232is @dfn{free}; this means that everyone is free to use it and 233free to redistribute it on a free basis. The library is not in the public 234domain; it is copyrighted and there are restrictions on its distribution, but 235these restrictions are designed to permit everything that a good cooperating 236citizen would want to do. What is not allowed is to try to prevent others 237from further sharing any version of this library that they might get from 238you.@refill 239 240Specifically, we want to make sure that you have the right to give away copies 241of the library, that you receive source code or else can get it if you want 242it, that you can change this library or use pieces of it in new free programs, 243and that you know you can do these things.@refill 244 245To make sure that everyone has such rights, we have to forbid you to deprive 246anyone else of these rights. For example, if you distribute copies of the 247GNU MPFR library, you must give the recipients all the rights that you have. 248You must make sure that they, too, receive or can get the source code. And you 249must tell them their rights.@refill 250 251Also, for our own protection, we must make certain that everyone finds out 252that there is no warranty for the GNU MPFR library. If it is modified by 253someone else and passed on, we want their recipients to know that what they 254have is not what we distributed, so that any problems introduced by others 255will not reflect on our reputation.@refill 256 257The precise conditions of the license for the GNU MPFR library are found in the 258Lesser General Public License that accompanies the source code. 259See the file COPYING.LESSER.@refill 260 261@node Introduction to MPFR, Installing MPFR, Copying, Top 262@comment node-name, next, previous, up 263@chapter Introduction to MPFR 264 265 266MPFR is a portable library written in C for arbitrary precision arithmetic 267on floating-point numbers. It is based on the GNU MP library. 268It aims to provide a class of floating-point numbers with 269precise semantics. The main characteristics of MPFR, which make it differ 270from most arbitrary precision floating-point software tools, are: 271 272@itemize @bullet 273@item the MPFR code is portable, i.e., the result of any operation 274does not depend on the machine word size 275@code{mp_bits_per_limb} (64 on most current processors); 276@item the precision in bits can be set @emph{exactly} to any valid value 277for each variable (including very small precision); 278@item MPFR provides the four rounding modes from the IEEE 754-1985 279standard, plus away-from-zero, as well as for basic operations as for other 280mathematical functions. 281@end itemize 282 283In particular, with a precision of 53 bits, MPFR is able to 284exactly reproduce all computations with double-precision machine 285floating-point numbers (e.g., @code{double} type in C, with a C 286implementation that rigorously follows Annex F of the ISO C99 standard 287and @code{FP_CONTRACT} pragma set to @code{OFF}) on the four arithmetic 288operations and the square root, except the default exponent range is much 289wider and subnormal numbers are not implemented (but can be emulated). 290 291This version of MPFR is released under the GNU Lesser General Public 292License, version 3 or any later version. 293It is permitted to link MPFR to most non-free programs, as long as when 294distributing them the MPFR source code and a means to re-link with a 295modified MPFR library is provided. 296 297@section How to Use This Manual 298 299Everyone should read @ref{MPFR Basics}. If you need to install the library 300yourself, you need to read @ref{Installing MPFR}, too. 301To use the library you will need to refer to @ref{MPFR Interface}. 302 303The rest of the manual can be used for later reference, although it is 304probably a good idea to glance through it. 305 306@node Installing MPFR, Reporting Bugs, Introduction to MPFR, Top 307@comment node-name, next, previous, up 308@chapter Installing MPFR 309@cindex Installation 310 311The MPFR library is already installed on some GNU/Linux distributions, 312but the development files necessary to the compilation such as 313@file{mpfr.h} are not always present. To check that MPFR is fully 314installed on your computer, you can check the presence of the file 315@file{mpfr.h} in @file{/usr/include}, or try to compile a small program 316having @code{#include <mpfr.h>} (since @file{mpfr.h} may be installed 317somewhere else). For instance, you can try to compile: 318 319@example 320#include <stdio.h> 321#include <mpfr.h> 322int main (void) 323@{ 324 printf ("MPFR library: %-12s\nMPFR header: %s (based on %d.%d.%d)\n", 325 mpfr_get_version (), MPFR_VERSION_STRING, MPFR_VERSION_MAJOR, 326 MPFR_VERSION_MINOR, MPFR_VERSION_PATCHLEVEL); 327 return 0; 328@} 329@end example 330 331@noindent 332with 333 334@example 335cc -o version version.c -lmpfr -lgmp 336@end example 337 338@noindent 339and if you get errors whose first line looks like 340 341@example 342version.c:2:19: error: mpfr.h: No such file or directory 343@end example 344 345@noindent 346then MPFR is probably not installed. Running this program will give you 347the MPFR version. 348 349If MPFR is not installed on your computer, or if you want to install a 350different version, please follow the steps below. 351 352@section How to Install 353 354Here are the steps needed to install the library on Unix systems 355(more details are provided in the @file{INSTALL} file): 356 357@enumerate 358@item 359To build MPFR, you first have to install GNU MP 360(version 4.1 or higher) on your computer. 361You need a C compiler, preferably GCC, but any reasonable compiler should 362work. And you need the standard Unix @samp{make} command, plus some other 363standard Unix utility commands. 364 365Then, in the MPFR build directory, type the following commands. 366 367@item 368@samp{./configure} 369 370This will prepare the build and setup the options according to your system. 371You can give options to specify the install directories (instead of 372the default @file{/usr/local}), threading support, and so on. See 373the @file{INSTALL} file and/or the output of @samp{./configure --help} 374for more information, in particular if you get error messages. 375 376@item 377@samp{make} 378 379This will compile MPFR, and create a library archive file @file{libmpfr.a}. 380On most platforms, a dynamic library will be produced too. 381@item 382@samp{make check} 383 384This will make sure MPFR was built correctly. 385If you get error messages, please 386report this to @samp{mpfr@@loria.fr}. (@xref{Reporting Bugs}, for 387information on what to include in useful bug reports.) 388 389@item 390@samp{make install} 391 392This will copy the files @file{mpfr.h} and @file{mpf2mpfr.h} to the directory 393@file{/usr/local/include}, the library files (@file{libmpfr.a} and possibly 394others) to the directory @file{/usr/local/lib}, the file @file{mpfr.info} 395to the directory @file{/usr/local/share/info}, and some other documentation 396files to the directory @file{/usr/local/share/doc/mpfr} (or if you passed the 397@samp{--prefix} option to @file{configure}, using the prefix directory given 398as argument to @samp{--prefix} instead of @file{/usr/local}). 399@end enumerate 400 401@section Other `make' Targets 402 403There are some other useful make targets: 404 405@itemize @bullet 406@item 407@samp{mpfr.info} or @samp{info} 408 409Create or update an info version of the manual, in @file{mpfr.info}. 410 411This file is already provided in the MPFR archives. 412 413@item 414@samp{mpfr.pdf} or @samp{pdf} 415 416Create a PDF version of the manual, in @file{mpfr.pdf}. 417 418@item 419@samp{mpfr.dvi} or @samp{dvi} 420 421Create a DVI version of the manual, in @file{mpfr.dvi}. 422 423@item 424@samp{mpfr.ps} or @samp{ps} 425 426Create a Postscript version of the manual, in @file{mpfr.ps}. 427 428@item 429@samp{mpfr.html} or @samp{html} 430 431Create a HTML version of the manual, in several pages in the directory 432@file{mpfr.html}; if you want only one output HTML file, then type 433@samp{makeinfo --html --no-split mpfr.texi} instead. 434 435@item 436@samp{clean} 437 438Delete all object files and archive files, but not the configuration files. 439 440@item 441@samp{distclean} 442 443Delete all generated files not included in the distribution. 444 445@item 446@samp{uninstall} 447 448Delete all files copied by @samp{make install}. 449@end itemize 450 451 452@section Build Problems 453 454In case of problem, please read the @file{INSTALL} file carefully 455before reporting a bug, in particular section ``In case of problem''. 456Some problems are due to bad configuration on the user side (not 457specific to MPFR). Problems are also mentioned in the FAQ 458@url{http://www.mpfr.org/faq.html}. 459 460@comment Warning! Do not split "MPFR ... @url{...}" across several lines 461@comment as this needs to be updated with update-version. 462Please report problems to @samp{mpfr@@loria.fr}. 463@xref{Reporting Bugs}. 464Some bug fixes are available on the 465MPFR 3.0.1 web page @url{http://www.mpfr.org/mpfr-3.0.1/}. 466 467@section Getting the Latest Version of MPFR 468 469The latest version of MPFR is available from 470@url{ftp://ftp.gnu.org/gnu/mpfr/} or @url{http://www.mpfr.org/}. 471 472@node Reporting Bugs, MPFR Basics, Installing MPFR, Top 473@comment node-name, next, previous, up 474@chapter Reporting Bugs 475@cindex Reporting bugs 476 477@comment Warning! Do not split "MPFR ... @url{...}" across several lines 478@comment as this needs to be updated with update-version. 479If you think you have found a bug in the MPFR library, first have a look 480on the MPFR 3.0.1 web page @url{http://www.mpfr.org/mpfr-3.0.1/} and the 481FAQ @url{http://www.mpfr.org/faq.html}: 482perhaps this bug is already known, in which case you may find there 483a workaround for it. 484You might also look in the archives of the MPFR mailing-list: 485@url{http://websympa.loria.fr/wwsympa/arc/mpfr}. 486Otherwise, please investigate and report it. 487We have made this library available to you, and it is not to ask too 488much from you, to ask you to report the bugs that you find. 489 490There are a few things you should think about when you put your bug report 491together. 492 493You have to send us a test case that makes it possible for us to reproduce the 494bug, i.e., a small self-content program, using no other library than MPFR. 495Include instructions on how to run the test case. 496 497You also have to explain what is wrong; if you get a crash, or if the results 498you get are incorrect and in that case, in what way. 499 500Please include compiler version information in your bug report. This can 501be extracted using @samp{cc -V} on some machines, or, if you're using GCC, 502@samp{gcc -v}. Also, include the output from @samp{uname -a} and the MPFR 503version (the GMP version may be useful too). 504 505If your bug report is good, we will do our best to help you to get a corrected 506version of the library; if the bug report is poor, we will not do anything 507about it (aside of chiding you to send better bug reports). 508 509Send your bug report to: @samp{mpfr@@loria.fr}. 510 511If you think something in this manual is unclear, or downright incorrect, or if 512the language needs to be improved, please send a note to the same address. 513 514@node MPFR Basics, MPFR Interface, Reporting Bugs, Top 515@comment node-name, next, previous, up 516@chapter MPFR Basics 517 518@section Headers and Libraries 519 520@cindex @file{mpfr.h} 521All declarations needed to use MPFR are collected in the include file 522@file{mpfr.h}. It is designed to work with both C and C++ compilers. 523You should include that file in any program using the MPFR library: 524 525@example 526#include <mpfr.h> 527@end example 528 529@cindex @code{stdio.h} 530Note however that prototypes for MPFR functions with @code{FILE *} parameters 531are provided only if @code{<stdio.h>} is included too (before @file{mpfr.h}): 532 533@example 534#include <stdio.h> 535#include <mpfr.h> 536@end example 537 538@cindex @code{stdarg.h} 539Likewise @code{<stdarg.h>} (or @code{<varargs.h>}) is required for prototypes 540with @code{va_list} parameters, such as @code{mpfr_vprintf}. 541 542@cindex @code{stdint.h} 543@cindex @code{inttypes.h} 544@cindex @code{intmax_t} 545@cindex @code{uintmax_t} 546And for any functions using @code{intmax_t}, you must include 547@code{<stdint.h>} or @code{<inttypes.h>} before @file{mpfr.h}, to 548allow @file{mpfr.h} to define prototypes for these functions. Moreover, 549users of C++ compilers under some platforms may need to define 550@code{MPFR_USE_INTMAX_T} (and should do it for portability) before 551@file{mpfr.h} has been included; of course, it is possible to do that 552on the command line, e.g., with @code{-DMPFR_USE_INTMAX_T}. 553 554Note: If @code{mpfr.h} and/or @code{gmp.h} (used by @code{mpfr.h}) 555are included several times (possibly from another header file), the 556aforementioned standard headers should be included @strong{before} the 557first inclusion of @code{mpfr.h} or @code{gmp.h}. For the time being, 558this problem is not avoidable in MPFR without a change in GMP. 559 560When calling a MPFR macro, it is not allowed to have previously defined 561a macro with the same name as some keywords (currently @code{do}, 562@code{while} and @code{sizeof}). 563 564You can avoid the use of MPFR macros encapsulating functions by defining 565the @samp{MPFR_USE_NO_MACRO} macro before @file{mpfr.h} is included. In 566general this should not be necessary, but this can be useful when debugging 567user code: with some macros, the compiler may emit spurious warnings with 568some warning options, and macros can prevent some prototype checking. 569 570@cindex Libraries 571@cindex Linking 572@cindex @code{libmpfr} 573All programs using MPFR must link against both @file{libmpfr} and 574@file{libgmp} libraries. On a typical Unix-like system this can be 575done with @samp{-lmpfr -lgmp} (in that order), for example: 576 577@example 578gcc myprogram.c -lmpfr -lgmp 579@end example 580 581@cindex Libtool 582MPFR is built using Libtool and an application can use that to link if 583desired, @MPFRpxreftop{libtool.info, GNU Libtool} 584@c Note: the .info extension has been added to avoid the following bug: 585@c http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=484740 586@c which occurs when reading the info file from the build directory: 587@c info ./mpfr or info -f ./mpfr.info 588@c Due to a poor design, the "info" utility will not find the correct 589@c libtool info file if the .info extension is not provided, because of 590@c the "libtool" script in MPFR's directory! 591 592If MPFR has been installed to a non-standard location, then it may be 593necessary to set up environment variables such as @samp{C_INCLUDE_PATH} 594and @samp{LIBRARY_PATH}, or use @samp{-I} and @samp{-L} compiler options, 595in order to point to the right directories. For a shared library, it may 596also be necessary to set up some sort of run-time library path (e.g., 597@samp{LD_LIBRARY_PATH}) on some systems. Please read the @file{INSTALL} 598file for additional information. 599 600@section Nomenclature and Types 601 602@cindex Floating-point number 603@tindex @code{mpfr_t} 604@noindent 605A @dfn{floating-point number}, or @dfn{float} for short, is an arbitrary 606precision significand (also called mantissa) with a limited precision 607exponent. The C data type 608for such objects is @code{mpfr_t} (internally defined as a one-element 609array of a structure, and @code{mpfr_ptr} is the C data type representing 610a pointer to this structure). A floating-point number can have 611three special values: Not-a-Number (NaN) or plus or minus Infinity. NaN 612represents an uninitialized object, the result of an invalid operation 613(like 0 divided by 0), or a value that cannot be determined (like 614+Infinity minus +Infinity). Moreover, like in the IEEE 754 standard, 615zero is signed, i.e., there are both +0 and @minus{}0; the behavior 616is the same as in the IEEE 754 standard and it is generalized to 617the other functions supported by MPFR. Unless documented otherwise, 618the sign bit of a NaN is unspecified. 619@c VL: re-added how mpfr_t is defined, due to some questions from users 620@c in the past (the fact that the result was returned in an argument 621@c seemed strange); also, mpfr_ptr needs to be defined here, as it is 622@c used in the API. 623 624@cindex Precision 625@tindex @code{mpfr_prec_t} 626@noindent 627The @dfn{precision} is the number of bits used to represent the significand 628of a floating-point number; 629the corresponding C data type is @code{mpfr_prec_t}. 630The precision can be any integer between @code{MPFR_PREC_MIN} and 631@code{MPFR_PREC_MAX}. In the current implementation, @code{MPFR_PREC_MIN} 632is equal to 2. 633 634Warning! MPFR needs to increase the precision internally, in order to 635provide accurate results (and in particular, correct rounding). Do not 636attempt to set the precision to any value near @code{MPFR_PREC_MAX}, 637otherwise MPFR will abort due to an assertion failure. Moreover, you 638may reach some memory limit on your platform, in which case the program 639may abort, crash or have undefined behavior (depending on your C 640implementation). 641 642@cindex Rounding Modes 643@tindex @code{mpfr_rnd_t} 644@noindent 645The @dfn{rounding mode} specifies the way to round the result of a 646floating-point operation, in case the exact result can not be represented 647exactly in the destination significand; 648the corresponding C data type is @code{mpfr_rnd_t}. 649 650@section MPFR Variable Conventions 651 652Before you can assign to an MPFR variable, you need to initialize it by calling 653one of the special initialization functions. When you're done with a 654variable, you need to clear it out, using one of the functions for that 655purpose. 656A variable should only be initialized once, or at least cleared out between 657each initialization. After a variable has been initialized, it may be 658assigned to any number of times. 659For efficiency reasons, avoid to initialize and clear out a variable in loops. 660Instead, initialize it before entering the loop, and clear it out after the 661loop has exited. 662You do not need to be concerned about allocating additional space for MPFR 663variables, since any variable has a significand of fixed size. 664Hence unless you change its precision, or clear and reinitialize it, 665a floating-point variable will have the same allocated space during all its 666life. 667 668As a general rule, all MPFR functions expect output arguments before input 669arguments. This notation is based on an analogy with the assignment operator. 670MPFR allows you to use the same variable for both input and output in the same 671expression. For example, the main function for floating-point multiplication, 672@code{mpfr_mul}, can be used like this: @code{mpfr_mul (x, x, x, rnd)}. 673This 674computes the square of @var{x} with rounding mode @code{rnd} 675and puts the result back in @var{x}. 676 677@section Rounding Modes 678 679The following five rounding modes are supported: 680 681@itemize @bullet 682@item @code{MPFR_RNDN}: round to nearest (roundTiesToEven in IEEE 754-2008), 683@item @code{MPFR_RNDZ}: round toward zero (roundTowardZero in IEEE 754-2008), 684@item @code{MPFR_RNDU}: round toward plus infinity (roundTowardPositive in IEEE 754-2008), 685@item @code{MPFR_RNDD}: round toward minus infinity (roundTowardNegative in IEEE 754-2008), 686@item @code{MPFR_RNDA}: round away from zero (experimental). 687@end itemize 688 689The @samp{round to nearest} mode works as in the IEEE 754 standard: in 690case the number to be rounded lies exactly in the middle of two representable 691numbers, it is rounded to the one with the least significant bit set to zero. 692For example, the number 2.5, which is represented by (10.1) in binary, is 693rounded to (10.0)=2 with a precision of two bits, and not to (11.0)=3. 694This rule avoids the @dfn{drift} phenomenon mentioned by Knuth in volume 2 695of The Art of Computer Programming (Section 4.2.2). 696 697Most MPFR functions take as first argument the destination variable, as 698second and following arguments the input variables, as last argument a 699rounding mode, and have a return value of type @code{int}, called the 700@dfn{ternary value}. The value stored in the destination variable is 701correctly rounded, i.e., MPFR behaves as if it computed the result with 702an infinite precision, then rounded it to the precision of this variable. 703The input variables are regarded as exact (in particular, their precision 704does not affect the result). 705 706As a consequence, in case of a non-zero real rounded result, the error 707on the result is less or equal to 1/2 ulp (unit in the last place) of 708that result in the rounding to nearest mode, and less than 1 ulp of that 709result in the directed rounding modes (a ulp is the weight of the least 710significant represented bit of the result after rounding). 711@c Since subnormals are not supported, we must take into account the ulp of 712@c the rounded result, not the one of the exact result, for full generality. 713 714Unless documented otherwise, functions returning an @code{int} return 715a ternary value. 716If the ternary value is zero, it means that the value stored in the 717destination variable is the exact result of the corresponding mathematical 718function. If the ternary value is positive (resp.@: negative), it means 719the value stored in the destination variable is greater (resp.@: lower) 720than the exact result. For example with the @code{MPFR_RNDU} rounding mode, 721the ternary value is usually positive, except when the result is exact, in 722which case it is zero. In the case of an infinite result, it is considered 723as inexact when it was obtained by overflow, and exact otherwise. A NaN 724result (Not-a-Number) always corresponds to an exact return value. 725The opposite of a returned ternary value is guaranteed to be representable 726in an @code{int}. 727 728Unless documented otherwise, functions returning as result the value @code{1} 729(or any other value specified in this manual) 730for special cases (like @code{acos(0)}) yield an overflow or 731an underflow if that value is not representable in the current exponent range. 732 733@section Floating-Point Values on Special Numbers 734 735This section specifies the floating-point values (of type @code{mpfr_t}) 736returned by MPFR functions (where by ``returned'' we mean here the modified 737value of the destination object, which should not be mixed with the ternary 738return value of type @code{int} of those functions). 739For functions returning several values (like 740@code{mpfr_sin_cos}), the rules apply to each result separately. 741 742Functions can have one or several input arguments. An input point is 743a mapping from these input arguments to the set of the MPFR numbers. 744When none of its components are NaN, an input point can also be seen 745as a tuple in the extended real numbers (the set of the real numbers 746with both infinities). 747 748When the input point is in the domain of the mathematical function, the 749result is rounded as described in Section ``Rounding Modes'' (but see 750below for the specification of the sign of an exact zero). Otherwise 751the general rules from this section apply unless stated otherwise in 752the description of the MPFR function (@ref{MPFR Interface}). 753 754When the input point is not in the domain of the mathematical function 755but is in its closure in the extended real numbers and the function can 756be extended by continuity, the result is the obtained limit. 757Examples: @code{mpfr_hypot} on (+Inf,0) gives +Inf. But @code{mpfr_pow} 758cannot be defined on (1,+Inf) using this rule, as one can find 759sequences (@m{x_n,@var{x}_@var{n}},@m{y_n,@var{y}_@var{n}}) such that 760@m{x_n,@var{x}_@var{n}} goes to 1, @m{y_n,@var{y}_@var{n}} goes to +Inf 761and @m{(x_n)^{y_n},@var{x}_@var{n} to the @var{y}_@var{n}} goes to any 762positive value when @var{n} goes to the infinity. 763 764When the input point is in the closure of the domain of the mathematical 765function and an input argument is +0 (resp.@: @minus{}0), one considers 766the limit when the corresponding argument approaches 0 from above 767(resp.@: below). If the limit is not defined (e.g., @code{mpfr_log} on 768@minus{}0), the behavior is specified in the description of the MPFR function. 769 770When the result is equal to 0, its sign is determined by considering the 771limit as if the input point were not in the domain: If one approaches 0 772from above (resp.@: below), the result is +0 (resp.@: @minus{}0); 773for example, @code{mpfr_sin} on +0 gives +0. 774In the other cases, the sign is specified in the description of the MPFR 775function; for example @code{mpfr_max} on @minus{}0 and +0 gives +0. 776 777When the input point is not in the closure of the domain of the function, 778the result is NaN. Example: @code{mpfr_sqrt} on @minus{}17 gives NaN. 779 780When an input argument is NaN, the result is NaN, possibly except when 781a partial function is constant on the finite floating-point numbers; 782such a case is always explicitly specified in @ref{MPFR Interface}. 783@c Said otherwise, if such a case is not specified, this is a bug, thus 784@c we may change the returned value after documenting it without having 785@c to change the libtool interface number (this would have more drawbacks 786@c that advantages in practice), like for any bug fix. 787Example: @code{mpfr_hypot} on (NaN,0) gives NaN, but @code{mpfr_hypot} 788on (NaN,+Inf) gives +Inf (as specified in @ref{Special Functions}), 789since for any finite input @var{x}, @code{mpfr_hypot} on (@var{x},+Inf) 790gives +Inf. 791 792@section Exceptions 793 794MPFR supports 5 exception types: 795 796@itemize @bullet 797 798@item Underflow: 799An underflow occurs when the exact result of a function is a non-zero 800real number and the result obtained after the rounding, assuming an 801unbounded exponent range (for the rounding), has an exponent smaller 802than the minimum value of the current exponent range. (In the round-to-nearest 803mode, the halfway case is rounded toward zero.) 804 805Note: This is not the single possible definition of the underflow. MPFR chooses 806to consider the underflow @emph{after} rounding. The underflow before rounding 807can also be defined. For instance, consider a function that has the 808exact result @m{7 \times 2^{e-4}, 7 multiplied by two to the power 809@var{e}@minus{}4}, where @var{e} is the smallest exponent (for a 810significand between 1/2 and 1), 811with a 2-bit target precision and rounding toward plus infinity. 812The exact result has the exponent @var{e}@minus{}1. With the underflow 813before rounding, such a function call would yield an underflow, as 814@var{e}@minus{}1 is outside the current exponent range. However, MPFR 815first considers the rounded result assuming an unbounded exponent range. 816The exact result cannot be represented exactly in precision 2, and here, 817it is rounded to @m{0.5 @times 2^e, 0.5 times 2 to @var{e}}, which is 818representable in the current exponent range. As a consequence, this will 819not yield an underflow in MPFR. 820 821@item Overflow: 822An overflow occurs when the exact result of a function is a non-zero 823real number and the result obtained after the rounding, assuming an 824unbounded exponent range (for the rounding), has an exponent larger 825than the maximum value of the current exponent range. In the round-to-nearest 826mode, the result is infinite. 827Note: unlike the underflow case, there is only one possible definition of 828overflow here. 829 830@item NaN: 831A NaN exception occurs when the result of a function is NaN. 832@c NaN is defined above. So, we don't say anything more. 833 834@item Inexact: 835An inexact exception occurs when the result of a function cannot be 836represented exactly and must be rounded. 837 838@item Range error: 839A range exception occurs when a function that does not return a MPFR 840number (such as comparisons and conversions to an integer) has an 841invalid result (e.g., an argument is NaN in @code{mpfr_cmp}, or a 842conversion to an integer cannot be represented in the target type). 843 844@end itemize 845 846MPFR has a global flag for each exception, which can be cleared, set 847or tested by functions described in @ref{Exception Related Functions}. 848 849Differences with the ISO C99 standard: 850 851@itemize @bullet 852 853@item In C, only quiet NaNs are specified, and a NaN propagation does not 854raise an invalid exception. Unless explicitly stated otherwise, MPFR sets 855the NaN flag whenever a NaN is generated, even when a NaN is propagated 856(e.g., in NaN + NaN), as if all NaNs were signaling. 857 858@item An invalid exception in C corresponds to either a NaN exception or 859a range error in MPFR. 860 861@end itemize 862 863@section Memory Handling 864 865MPFR functions may create caches, e.g., when computing constants such 866as @m{\pi,Pi}, either because the user has called a function like 867@code{mpfr_const_pi} directly or because such a function was called 868internally by the MPFR library itself to compute some other function. 869 870At any time, the user can free the various caches with 871@code{mpfr_free_cache}. It is strongly advised to do that before 872terminating a thread, or before exiting when using tools like 873@samp{valgrind} (to avoid memory leaks being reported). 874 875MPFR internal data such as flags, the exponent range, the default 876precision and rounding mode, and caches (i.e., data that are not 877accessed via parameters) are either global (if MPFR has not been 878compiled as thread safe) or per-thread (thread local storage). 879 880@node MPFR Interface, API Compatibility, MPFR Basics, Top 881@comment node-name, next, previous, up 882@chapter MPFR Interface 883@cindex Floating-point functions 884@cindex Float functions 885 886The floating-point functions expect arguments of type @code{mpfr_t}. 887 888The MPFR floating-point functions have an interface that is similar to the 889GNU MP 890functions. The function prefix for floating-point operations is @code{mpfr_}. 891 892The user has 893to specify the precision of each variable. A computation that assigns a 894variable will take place with the precision of the assigned variable; the 895cost of that computation should not depend on the 896precision of variables used as input (on average). 897 898@cindex Precision 899The semantics of a calculation in MPFR is specified as follows: Compute the 900requested operation exactly (with ``infinite accuracy''), and round the result 901to the precision of the destination variable, with the given rounding mode. 902The MPFR floating-point functions are intended to be a smooth extension 903of the IEEE 754 arithmetic. The results obtained on a given computer are 904identical to those obtained on a computer with a different word size, 905or with a different compiler or operating system. 906 907@cindex Accuracy 908MPFR @emph{does not keep track} of the accuracy of a computation. This is left 909to the user or to a higher layer (for example the MPFI library for interval 910arithmetic). 911As a consequence, if two variables are used to store 912only a few significant bits, and their product is stored in a variable with large 913precision, then MPFR will still compute the result with full precision. 914 915The value of the standard C macro @code{errno} may be set to non-zero by 916any MPFR function or macro, whether or not there is an error. 917 918@menu 919* Initialization Functions:: 920* Assignment Functions:: 921* Combined Initialization and Assignment Functions:: 922* Conversion Functions:: 923* Basic Arithmetic Functions:: 924* Comparison Functions:: 925* Special Functions:: 926* Input and Output Functions:: 927* Formatted Output Functions:: 928* Integer Related Functions:: 929* Rounding Related Functions:: 930* Miscellaneous Functions:: 931* Exception Related Functions:: 932* Compatibility with MPF:: 933* Custom Interface:: 934* Internals:: 935@end menu 936 937@node Initialization Functions, Assignment Functions, MPFR Interface, MPFR Interface 938@comment node-name, next, previous, up 939@cindex Initialization functions 940@section Initialization Functions 941 942An @code{mpfr_t} object must be initialized before storing the first value in 943it. The functions @code{mpfr_init} and @code{mpfr_init2} are used for that 944purpose. 945 946@deftypefun void mpfr_init2 (mpfr_t @var{x}, mpfr_prec_t @var{prec}) 947Initialize @var{x}, set its precision to be @strong{exactly} 948@var{prec} bits and its value to NaN. (Warning: the corresponding 949MPF function initializes to zero instead.) 950 951Normally, a variable should be initialized once only or at 952least be cleared, using @code{mpfr_clear}, between initializations. 953To change the precision of a variable which has already been initialized, 954use @code{mpfr_set_prec}. 955The precision @var{prec} must be an integer between @code{MPFR_PREC_MIN} and 956@code{MPFR_PREC_MAX} (otherwise the behavior is undefined). 957@end deftypefun 958 959@deftypefun void mpfr_inits2 (mpfr_prec_t @var{prec}, mpfr_t @var{x}, ...) 960Initialize all the @code{mpfr_t} variables of the given variable 961argument @code{va_list}, set their precision to be @strong{exactly} 962@var{prec} bits and their value to NaN. 963See @code{mpfr_init2} for more details. 964The @code{va_list} is assumed to be composed only of type @code{mpfr_t} 965(or equivalently @code{mpfr_ptr}). 966It begins from @var{x}, and ends when it encounters a null pointer (whose 967type must also be @code{mpfr_ptr}). 968@end deftypefun 969 970@deftypefun void mpfr_clear (mpfr_t @var{x}) 971Free the space occupied by the significand of 972@var{x}. Make sure to call this function for all 973@code{mpfr_t} variables when you are done with them. 974@end deftypefun 975 976@deftypefun void mpfr_clears (mpfr_t @var{x}, ...) 977Free the space occupied by all the @code{mpfr_t} variables of the given 978@code{va_list}. See @code{mpfr_clear} for more details. 979The @code{va_list} is assumed to be composed only of type @code{mpfr_t} 980(or equivalently @code{mpfr_ptr}). 981It begins from @var{x}, and ends when it encounters a null pointer (whose 982type must also be @code{mpfr_ptr}). 983@end deftypefun 984 985Here is an example of how to use multiple initialization functions 986(since @code{NULL} is not necessarily defined in this context, we use 987@code{(mpfr_ptr) 0} instead, but @code{(mpfr_ptr) NULL} is also correct). 988 989@example 990@{ 991 mpfr_t x, y, z, t; 992 mpfr_inits2 (256, x, y, z, t, (mpfr_ptr) 0); 993 @dots{} 994 mpfr_clears (x, y, z, t, (mpfr_ptr) 0); 995@} 996@end example 997 998@deftypefun void mpfr_init (mpfr_t @var{x}) 999Initialize @var{x}, set its precision to the default precision, 1000and set its value to NaN. 1001The default precision can be changed by a call to @code{mpfr_set_default_prec}. 1002 1003Warning! In a given program, some other libraries might change the default 1004precision and not restore it. Thus it is safer to use @code{mpfr_init2}. 1005@end deftypefun 1006 1007@deftypefun void mpfr_inits (mpfr_t @var{x}, ...) 1008Initialize all the @code{mpfr_t} variables of the given @code{va_list}, 1009set their precision to the default precision and their value to NaN. 1010See @code{mpfr_init} for more details. 1011The @code{va_list} is assumed to be composed only of type @code{mpfr_t} 1012(or equivalently @code{mpfr_ptr}). 1013It begins from @var{x}, and ends when it encounters a null pointer (whose 1014type must also be @code{mpfr_ptr}). 1015 1016Warning! In a given program, some other libraries might change the default 1017precision and not restore it. Thus it is safer to use @code{mpfr_inits2}. 1018@end deftypefun 1019 1020@defmac MPFR_DECL_INIT (@var{name}, @var{prec}) 1021This macro declares @var{name} as an automatic variable of type @code{mpfr_t}, 1022initializes it and sets its precision to be @strong{exactly} @var{prec} bits 1023and its value to NaN. @var{name} must be a valid identifier. 1024You must use this macro in the declaration section. 1025This macro is much faster than using @code{mpfr_init2} but has some 1026drawbacks: 1027 1028@itemize @bullet 1029@item You @strong{must not} call @code{mpfr_clear} with variables 1030created with this macro (the storage is allocated at the point of declaration 1031and deallocated when the brace-level is exited). 1032@item You @strong{cannot} change their precision. 1033@item You @strong{should not} create variables with huge precision with this 1034macro. 1035@item Your compiler must support @samp{Non-Constant Initializers} (standard 1036in C++ and ISO C99) and @samp{Token Pasting} 1037(standard in ISO C89). If @var{prec} is not a constant expression, your 1038compiler must support @samp{variable-length automatic arrays} (standard 1039in ISO C99). GCC 2.95.3 and above supports all these features. 1040If you compile your program with GCC in C89 mode and with @samp{-pedantic}, 1041you may want to define the @code{MPFR_USE_EXTENSION} macro to avoid warnings 1042due to the @code{MPFR_DECL_INIT} implementation. 1043@end itemize 1044@end defmac 1045 1046@deftypefun void mpfr_set_default_prec (mpfr_prec_t @var{prec}) 1047Set the default precision to be @strong{exactly} @var{prec} bits, where 1048@var{prec} can be any integer between @code{MPFR_PREC_MIN} and 1049@code{MPFR_PREC_MAX}. 1050The 1051precision of a variable means the number of bits used to store its significand. 1052All 1053subsequent calls to @code{mpfr_init} or @code{mpfr_inits} 1054will use this precision, but previously 1055initialized variables are unaffected. 1056The default precision is set to 53 bits initially. 1057@end deftypefun 1058 1059@deftypefun mpfr_prec_t mpfr_get_default_prec (void) 1060Return the current default MPFR precision in bits. 1061@end deftypefun 1062 1063@need 2000 1064Here is an example on how to initialize floating-point variables: 1065 1066@example 1067@{ 1068 mpfr_t x, y; 1069 mpfr_init (x); /* use default precision */ 1070 mpfr_init2 (y, 256); /* precision @emph{exactly} 256 bits */ 1071 @dots{} 1072 /* When the program is about to exit, do ... */ 1073 mpfr_clear (x); 1074 mpfr_clear (y); 1075 mpfr_free_cache (); /* free the cache for constants like pi */ 1076@} 1077@end example 1078 1079The following functions are useful for changing the precision during a 1080calculation. A typical use would be for adjusting the precision gradually in 1081iterative algorithms like Newton-Raphson, making the computation precision 1082closely match the actual accurate part of the numbers. 1083 1084@deftypefun void mpfr_set_prec (mpfr_t @var{x}, mpfr_prec_t @var{prec}) 1085Reset the precision of @var{x} to be @strong{exactly} @var{prec} bits, 1086and set its value to NaN. 1087The previous value stored in @var{x} is lost. It is equivalent to 1088a call to @code{mpfr_clear(x)} followed by a call to 1089@code{mpfr_init2(x, prec)}, but more efficient as no allocation is done in 1090case the current allocated space for the significand of @var{x} is enough. 1091The precision @var{prec} can be any integer between @code{MPFR_PREC_MIN} and 1092@code{MPFR_PREC_MAX}. 1093In case you want to keep the previous value stored in @var{x}, 1094use @code{mpfr_prec_round} instead. 1095@end deftypefun 1096 1097@deftypefun mpfr_prec_t mpfr_get_prec (mpfr_t @var{x}) 1098Return the precision of @var{x}, i.e., the 1099number of bits used to store its significand. 1100@end deftypefun 1101 1102@node Assignment Functions, Combined Initialization and Assignment Functions, Initialization Functions, MPFR Interface 1103@comment node-name, next, previous, up 1104@cindex Assignment functions 1105@section Assignment Functions 1106 1107These functions assign new values to already initialized floats 1108(@pxref{Initialization Functions}). 1109 1110@deftypefun int mpfr_set (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1111@deftypefunx int mpfr_set_ui (mpfr_t @var{rop}, unsigned long int @var{op}, mpfr_rnd_t @var{rnd}) 1112@deftypefunx int mpfr_set_si (mpfr_t @var{rop}, long int @var{op}, mpfr_rnd_t @var{rnd}) 1113@deftypefunx int mpfr_set_uj (mpfr_t @var{rop}, uintmax_t @var{op}, mpfr_rnd_t @var{rnd}) 1114@deftypefunx int mpfr_set_sj (mpfr_t @var{rop}, intmax_t @var{op}, mpfr_rnd_t @var{rnd}) 1115@deftypefunx int mpfr_set_flt (mpfr_t @var{rop}, float @var{op}, mpfr_rnd_t @var{rnd}) 1116@deftypefunx int mpfr_set_d (mpfr_t @var{rop}, double @var{op}, mpfr_rnd_t @var{rnd}) 1117@deftypefunx int mpfr_set_ld (mpfr_t @var{rop}, long double @var{op}, mpfr_rnd_t @var{rnd}) 1118@deftypefunx int mpfr_set_decimal64 (mpfr_t @var{rop}, _Decimal64 @var{op}, mpfr_rnd_t @var{rnd}) 1119@deftypefunx int mpfr_set_z (mpfr_t @var{rop}, mpz_t @var{op}, mpfr_rnd_t @var{rnd}) 1120@deftypefunx int mpfr_set_q (mpfr_t @var{rop}, mpq_t @var{op}, mpfr_rnd_t @var{rnd}) 1121@deftypefunx int mpfr_set_f (mpfr_t @var{rop}, mpf_t @var{op}, mpfr_rnd_t @var{rnd}) 1122Set the value of @var{rop} from @var{op}, rounded 1123toward the given direction @var{rnd}. 1124Note that the input 0 is converted to +0 by @code{mpfr_set_ui}, 1125@code{mpfr_set_si}, @code{mpfr_set_uj}, @code{mpfr_set_sj}, 1126@code{mpfr_set_z}, @code{mpfr_set_q} and 1127@code{mpfr_set_f}, regardless of the rounding mode. 1128If the system does not support the IEEE 754 standard, 1129@code{mpfr_set_flt}, @code{mpfr_set_d}, @code{mpfr_set_ld} and 1130@code{mpfr_set_decimal64} might not preserve the signed zeros. 1131The @code{mpfr_set_decimal64} function is built only with the configure 1132option @samp{--enable-decimal-float}, which also requires 1133@samp{--with-gmp-build}, and when the compiler or 1134system provides the @samp{_Decimal64} data type 1135(recent versions of GCC support this data type). 1136@c GCC 4.2.0 required to be configured with --enable-decimal-float 1137@c but GCC 4.4.3 seems to have decimal support by default 1138@code{mpfr_set_q} might fail if the numerator (or the 1139denominator) can not be represented as a @code{mpfr_t}. 1140 1141Note: If you want to store a floating-point constant to a @code{mpfr_t}, 1142you should use @code{mpfr_set_str} (or one of the MPFR constant functions, 1143such as @code{mpfr_const_pi} for @m{\pi,Pi}) instead of 1144@code{mpfr_set_flt}, @code{mpfr_set_d}, 1145@code{mpfr_set_ld} or @code{mpfr_set_decimal64}. 1146Otherwise the floating-point constant will be first 1147converted into a reduced-precision (e.g., 53-bit) binary number before 1148MPFR can work with it. 1149@end deftypefun 1150 1151@deftypefun int mpfr_set_ui_2exp (mpfr_t @var{rop}, unsigned long int @var{op}, mpfr_exp_t @var{e}, mpfr_rnd_t @var{rnd}) 1152@deftypefunx int mpfr_set_si_2exp (mpfr_t @var{rop}, long int @var{op}, mpfr_exp_t @var{e}, mpfr_rnd_t @var{rnd}) 1153@deftypefunx int mpfr_set_uj_2exp (mpfr_t @var{rop}, uintmax_t @var{op}, intmax_t @var{e}, mpfr_rnd_t @var{rnd}) 1154@deftypefunx int mpfr_set_sj_2exp (mpfr_t @var{rop}, intmax_t @var{op}, intmax_t @var{e}, mpfr_rnd_t @var{rnd}) 1155@deftypefunx int mpfr_set_z_2exp (mpfr_t @var{rop}, mpz_t @var{op}, mpfr_exp_t @var{e}, mpfr_rnd_t @var{rnd}) 1156Set the value of @var{rop} from @m{@var{op} \times 2^e, @var{op} multiplied by 1157two to the power @var{e}}, rounded toward the given direction @var{rnd}. 1158Note that the input 0 is converted to +0. 1159@end deftypefun 1160 1161@deftypefun int mpfr_set_str (mpfr_t @var{rop}, const char *@var{s}, int @var{base}, mpfr_rnd_t @var{rnd}) 1162Set @var{rop} to the value of the string @var{s} in base @var{base}, 1163rounded in the direction @var{rnd}. 1164See the documentation of @code{mpfr_strtofr} for a detailed description 1165of the valid string formats. 1166Contrary to @code{mpfr_strtofr}, @code{mpfr_set_str} requires the 1167@emph{whole} string to represent a valid floating-point number. 1168@c Additionally, special values 1169@c @code{@@NaN@@}, @code{@@Inf@@}, @code{+@@Inf@@} and @code{-@@Inf@@}, 1170@c all case insensitive, without leading whitespace and possibly followed by 1171@c other characters, are accepted too (it may change). 1172This function returns 0 if the entire string up to the final null character 1173is a valid number in base @var{base}; otherwise it returns @minus{}1, and 1174@var{rop} may have changed. 1175Note: it is preferable to use @code{mpfr_set_str} if one wants to distinguish 1176between an infinite @var{rop} value coming from an infinite @var{s} or from 1177an overflow. 1178@end deftypefun 1179 1180@deftypefun int mpfr_strtofr (mpfr_t @var{rop}, const char *@var{nptr}, char **@var{endptr}, int @var{base}, mpfr_rnd_t @var{rnd}) 1181 1182Read a floating-point number from a string @var{nptr} in base @var{base}, 1183rounded in the direction @var{rnd}; @var{base} must be either 0 (to 1184detect the base, as described below) or a number from 2 to 62 (otherwise 1185the behavior is undefined). If @var{nptr} starts with valid data, the 1186result is stored in @var{rop} and @code{*@var{endptr}} points to the 1187character just after the valid data (if @var{endptr} is not a null pointer); 1188otherwise @var{rop} is set to zero (for consistency with @code{strtod}) 1189and the value of @var{nptr} is stored 1190in the location referenced by @var{endptr} (if @var{endptr} is not a null 1191pointer). The usual ternary value is returned. 1192 1193Parsing follows the standard C @code{strtod} function with some extensions. 1194After optional leading whitespace, one has a subject sequence consisting of an 1195optional sign (@code{+} or @code{-}), and either numeric data or special 1196data. The subject sequence is defined as the longest initial subsequence of 1197the input string, starting with the first non-whitespace character, that is of 1198the expected form. 1199 1200The form of numeric data is a non-empty sequence of significand digits with an 1201optional decimal point, and an optional exponent consisting of an exponent 1202prefix followed by an optional sign and a non-empty sequence of decimal 1203digits. A significand digit is either a decimal digit or a Latin letter (62 1204possible characters), with @code{A} = 10, @code{B} = 11, @dots{}, @code{Z} = 120535; case is ignored in bases less or equal to 36, in bases larger than 36, 1206@code{a} = 36, @code{b} = 37, @dots{}, @code{z} = 61. 1207The value of a 1208significand digit must be strictly less than the base. The decimal point can 1209be either the one defined by the current locale or the period (the first one 1210is accepted for consistency with the C standard and the practice, the second 1211one is accepted to allow the programmer to provide MPFR numbers from strings 1212in a way that does not depend on the current locale). 1213The exponent prefix can be @code{e} or @code{E} for bases up to 10, or 1214@code{@@} in any base; it indicates a multiplication by a power of the 1215base. In bases 2 and 16, the exponent prefix can also be @code{p} or @code{P}, 1216in which case the exponent, called @emph{binary exponent}, indicates a 1217multiplication by a power of 2 instead of the base (there is a difference 1218only for base 16); in base 16 for example @code{1p2} represents 4 whereas 1219@code{1@@2} represents 256. The value of an exponent is always written in 1220base 10. 1221 1222If the argument @var{base} is 0, then the base is automatically detected 1223as follows. If the significand starts with @code{0b} or @code{0B}, base 2 1224is assumed. If the significand starts with @code{0x} or @code{0X}, base 16 1225is assumed. Otherwise base 10 is assumed. 1226 1227Note: The exponent (if present) 1228must contain at least a digit. Otherwise the possible 1229exponent prefix and sign are not part of the number (which ends with the 1230significand). Similarly, if @code{0b}, @code{0B}, @code{0x} or @code{0X} 1231is not followed by a binary/hexadecimal digit, then the subject sequence 1232stops at the character @code{0}, thus 0 is read. 1233 1234Special data (for infinities and NaN) can be @code{@@inf@@} or 1235@code{@@nan@@(n-char-sequence-opt)}, and if @math{@var{base} @le{} 16}, 1236it can also be @code{infinity}, @code{inf}, @code{nan} or 1237@code{nan(n-char-sequence-opt)}, all case insensitive. 1238A @code{n-char-sequence-opt} is a possibly empty string containing only digits, 1239Latin letters and the underscore (0, 1, 2, @dots{}, 9, a, b, @dots{}, z, 1240A, B, @dots{}, Z, _). Note: one has an optional sign for all data, even 1241NaN. 1242For example, @code{-@@nAn@@(This_Is_Not_17)} is a valid representation for NaN 1243in base 17. 1244 1245@end deftypefun 1246 1247@deftypefun void mpfr_set_nan (mpfr_t @var{x}) 1248@deftypefunx void mpfr_set_inf (mpfr_t @var{x}, int @var{sign}) 1249@deftypefunx void mpfr_set_zero (mpfr_t @var{x}, int @var{sign}) 1250Set the variable @var{x} to NaN (Not-a-Number), infinity or zero respectively. 1251In @code{mpfr_set_inf} or @code{mpfr_set_zero}, @var{x} is set to plus 1252infinity or plus zero iff @var{sign} is nonnegative; 1253in @code{mpfr_set_nan}, the sign bit of the result is unspecified. 1254@end deftypefun 1255 1256@deftypefun void mpfr_swap (mpfr_t @var{x}, mpfr_t @var{y}) 1257Swap the values @var{x} and @var{y} efficiently. Warning: the 1258precisions are exchanged too; in case the precisions are different, 1259@code{mpfr_swap} is thus not equivalent to three @code{mpfr_set} calls 1260using a third auxiliary variable. 1261@end deftypefun 1262 1263@node Combined Initialization and Assignment Functions, Conversion Functions, Assignment Functions, MPFR Interface 1264@comment node-name, next, previous, up 1265@cindex Combined initialization and assignment functions 1266@section Combined Initialization and Assignment Functions 1267 1268@deftypefn Macro int mpfr_init_set (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1269@deftypefnx Macro int mpfr_init_set_ui (mpfr_t @var{rop}, unsigned long int @var{op}, mpfr_rnd_t @var{rnd}) 1270@deftypefnx Macro int mpfr_init_set_si (mpfr_t @var{rop}, long int @var{op}, mpfr_rnd_t @var{rnd}) 1271@deftypefnx Macro int mpfr_init_set_d (mpfr_t @var{rop}, double @var{op}, mpfr_rnd_t @var{rnd}) 1272@deftypefnx Macro int mpfr_init_set_ld (mpfr_t @var{rop}, long double @var{op}, mpfr_rnd_t @var{rnd}) 1273@deftypefnx Macro int mpfr_init_set_z (mpfr_t @var{rop}, mpz_t @var{op}, mpfr_rnd_t @var{rnd}) 1274@deftypefnx Macro int mpfr_init_set_q (mpfr_t @var{rop}, mpq_t @var{op}, mpfr_rnd_t @var{rnd}) 1275@deftypefnx Macro int mpfr_init_set_f (mpfr_t @var{rop}, mpf_t @var{op}, mpfr_rnd_t @var{rnd}) 1276Initialize @var{rop} and set its value from @var{op}, rounded in the direction 1277@var{rnd}. 1278The precision of @var{rop} will be taken from the active default precision, 1279as set by @code{mpfr_set_default_prec}. 1280@end deftypefn 1281 1282@deftypefun int mpfr_init_set_str (mpfr_t @var{x}, const char *@var{s}, int @var{base}, mpfr_rnd_t @var{rnd}) 1283Initialize @var{x} and set its value from 1284the string @var{s} in base @var{base}, 1285rounded in the direction @var{rnd}. 1286See @code{mpfr_set_str}. 1287@end deftypefun 1288 1289@node Conversion Functions, Basic Arithmetic Functions, Combined Initialization and Assignment Functions, MPFR Interface 1290@comment node-name, next, previous, up 1291@cindex Conversion functions 1292@section Conversion Functions 1293 1294@deftypefun float mpfr_get_flt (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1295@deftypefunx double mpfr_get_d (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1296@deftypefunx {long double} mpfr_get_ld (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1297@deftypefunx _Decimal64 mpfr_get_decimal64 (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1298Convert @var{op} to a @code{float} (respectively @code{double}, 1299@code{long double} or @code{_Decimal64}), using the rounding mode @var{rnd}. 1300If @var{op} is NaN, some fixed NaN (either quiet or signaling) or the result 1301of 0.0/0.0 is returned. If @var{op} is @pom{}Inf, an infinity of the same 1302sign or the result of @pom{}1.0/0.0 is returned. If @var{op} is zero, these 1303functions return a zero, trying to preserve its sign, if possible. 1304The @code{mpfr_get_decimal64} function is built only under some conditions: 1305see the documentation of @code{mpfr_set_decimal64}. 1306@end deftypefun 1307 1308@deftypefun long mpfr_get_si (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1309@deftypefunx {unsigned long} mpfr_get_ui (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1310@deftypefunx intmax_t mpfr_get_sj (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1311@deftypefunx uintmax_t mpfr_get_uj (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1312Convert @var{op} to a @code{long}, an @code{unsigned long}, 1313an @code{intmax_t} or an @code{uintmax_t} (respectively) after rounding 1314it with respect to @var{rnd}. 1315If @var{op} is NaN, 0 is returned and the @emph{erange} flag is set. 1316If @var{op} is too big for the return type, the function returns the maximum 1317or the minimum of the corresponding C type, depending on the direction 1318of the overflow; the @emph{erange} flag is set too. 1319See also @code{mpfr_fits_slong_p}, @code{mpfr_fits_ulong_p}, 1320@code{mpfr_fits_intmax_p} and @code{mpfr_fits_uintmax_p}. 1321@end deftypefun 1322 1323@deftypefun double mpfr_get_d_2exp (long *@var{exp}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1324@deftypefunx {long double} mpfr_get_ld_2exp (long *@var{exp}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1325Return @var{d} and set @var{exp} 1326(formally, the value pointed to by @var{exp}) 1327such that @math{0.5@le{}@GMPabs{@var{d}}<1} 1328and @m{@var{d}\times 2^{exp}, @var{d} times 2 raised to @var{exp}} equals 1329@var{op} rounded to double (resp.@: long double) 1330precision, using the given rounding mode. 1331@comment See ISO C standard, frexp function. 1332If @var{op} is zero, then a zero of the same sign (or an unsigned zero, 1333if the implementation does not have signed zeros) is returned, and 1334@var{exp} is set to 0. 1335If @var{op} is NaN or an infinity, then the corresponding double precision 1336(resp.@: long-double precision) 1337value is returned, and @var{exp} is undefined. 1338@end deftypefun 1339 1340@deftypefun mpfr_exp_t mpfr_get_z_2exp (mpz_t @var{rop}, mpfr_t @var{op}) 1341Put the scaled significand of @var{op} (regarded as an integer, with the 1342precision of @var{op}) into @var{rop}, and return the exponent @var{exp} 1343(which may be outside the current exponent range) such that @var{op} 1344exactly equals 1345@ifnottex 1346@var{rop} times 2 raised to the power @var{exp}. 1347@end ifnottex 1348@tex 1349$rop \times 2^{\rm exp}$. 1350@end tex 1351If @var{op} is zero, the minimal exponent @code{emin} is returned. 1352If @var{op} is NaN or an infinity, the @emph{erange} flag is set, @var{rop} 1353is set to 0, and the the minimal exponent @code{emin} is returned. 1354The returned exponent may be less than the minimal exponent @code{emin} 1355of MPFR numbers in the current exponent range; in case the exponent is 1356not representable in the @code{mpfr_exp_t} type, the @emph{erange} flag 1357is set and the minimal value of the @code{mpfr_exp_t} type is returned. 1358@end deftypefun 1359 1360@deftypefun int mpfr_get_z (mpz_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1361Convert @var{op} to a @code{mpz_t}, after rounding it with respect to 1362@var{rnd}. If @var{op} is NaN or an infinity, the @emph{erange} flag is 1363set, @var{rop} is set to 0, and 0 is returned. 1364@end deftypefun 1365 1366@deftypefun int mpfr_get_f (mpf_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1367Convert @var{op} to a @code{mpf_t}, after rounding it with respect to 1368@var{rnd}. 1369@c Since we say it in the "API Compatibility" section, no need to say it here: 1370@c Return the usual ternary value. Notice that the meaning of the returned value 1371@c has changed since version 3.0. 1372The @emph{erange} flag is set if @var{op} is NaN or Inf, which do not exist in 1373MPF. 1374@end deftypefun 1375 1376@deftypefun {char *} mpfr_get_str (char *@var{str}, mpfr_exp_t *@var{expptr}, int @var{b}, size_t @var{n}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1377Convert @var{op} to a string of digits in base @var{b}, with rounding in 1378the direction @var{rnd}, where @var{n} is either zero (see below) or the 1379number of significant digits output in the string; 1380in the latter case, @var{n} must be greater 1381or equal to 2. The base may vary from 2 to 62. 1382If the input number is an ordinary number, the exponent is written through 1383the pointer @var{expptr} (for input 0, the current minimal exponent is 1384written). 1385 1386The generated string is a fraction, with an implicit radix point immediately 1387to the left of the first digit. For example, the number @minus{}3.1416 would 1388be returned as "@minus{}31416" in the string and 1 written at @var{expptr}. 1389If @var{rnd} is to nearest, and @var{op} is exactly in the middle of two 1390consecutive possible outputs, the one with an even significand is chosen, 1391where both significands are considered with the exponent of @var{op}. 1392Note that for an odd base, this may not correspond to an even last digit: 1393for example with 2 digits in base 7, (14) and a half is rounded to (15) 1394which is 12 in decimal, (16) and a half is rounded to 1395(20) which is 14 in decimal, 1396@c The following example duplicates (16) and a half 1397@c (36) and a half is rounded to (40) which is 28 in decimal, 1398and (26) and a half is rounded to (26) which is 20 in decimal. 1399 1400If @var{n} is zero, the number of digits of the significand is chosen 1401large enough so that re-reading the printed value with the same precision, 1402assuming both output and input use rounding to nearest, will recover 1403the original value of @var{op}. 1404More precisely, in most cases, the chosen precision of @var{str} is the 1405minimal precision @math{m} depending only on @var{p} = PREC(@var{op}) and 1406@var{b} that satisfies the above property, i.e., 1407@ifnottex 1408m = 1 + ceil(@var{p}*log(2)/log(@var{b})), 1409@end ifnottex 1410@tex 1411$m = 1 + \lceil p {\log 2 \over \log b} \rceil$, 1412@end tex 1413with @var{p} replaced by @var{p}@minus{}1 if @var{b} is a power of 2, 1414but in some very rare cases, it might be @math{m+1} 1415(the smallest case for bases up to 62 is when @var{p} equals 186564318007 1416for bases 7 and 49). 1417 1418If @var{str} is a null pointer, space for the significand is allocated using 1419the current allocation function, and a pointer to the string is returned. 1420To free the returned string, you must use @code{mpfr_free_str}. 1421 1422If @var{str} is not a null pointer, it should point to a block of storage 1423large enough for the significand, i.e., at least @code{max(@var{n} + 2, 7)}. 1424The extra two bytes are for a possible minus sign, and for the terminating null 1425character, and the value 7 accounts for @code{-@@Inf@@} 1426plus the terminating null character. 1427 1428A pointer to the string is returned, unless there is an error, in which 1429case a null pointer is returned. 1430@end deftypefun 1431 1432@deftypefun void mpfr_free_str (char *@var{str}) 1433Free a string allocated by @code{mpfr_get_str} using the current unallocation 1434function. 1435The block is assumed to be @code{strlen(@var{str})+1} bytes. 1436For more information about how it is done: 1437@ifinfo 1438@pxref{Custom Allocation,,, gmp.info,GNU MP}. 1439@end ifinfo 1440@ifnotinfo 1441see Section ``Custom Allocation'' in @cite{GNU MP}. 1442@end ifnotinfo 1443@end deftypefun 1444 1445@deftypefun int mpfr_fits_ulong_p (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1446@deftypefunx int mpfr_fits_slong_p (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1447@deftypefunx int mpfr_fits_uint_p (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1448@deftypefunx int mpfr_fits_sint_p (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1449@deftypefunx int mpfr_fits_ushort_p (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1450@deftypefunx int mpfr_fits_sshort_p (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1451@deftypefunx int mpfr_fits_uintmax_p (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1452@deftypefunx int mpfr_fits_intmax_p (mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1453Return non-zero if @var{op} would fit in the respective C data type, 1454respectively @code{unsigned long}, @code{long}, @code{unsigned int}, 1455@code{int}, @code{unsigned short}, @code{short}, @code{uintmax_t}, 1456@code{intmax_t}, when rounded to an integer in the direction @var{rnd}. 1457@end deftypefun 1458 1459@node Basic Arithmetic Functions, Comparison Functions, Conversion Functions, MPFR Interface 1460@comment node-name, next, previous, up 1461@cindex Basic arithmetic functions 1462@cindex Float arithmetic functions 1463@cindex Arithmetic functions 1464@section Basic Arithmetic Functions 1465 1466@deftypefun int mpfr_add (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1467@deftypefunx int mpfr_add_ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mpfr_rnd_t @var{rnd}) 1468@deftypefunx int mpfr_add_si (mpfr_t @var{rop}, mpfr_t @var{op1}, long int @var{op2}, mpfr_rnd_t @var{rnd}) 1469@deftypefunx int mpfr_add_d (mpfr_t @var{rop}, mpfr_t @var{op1}, double @var{op2}, mpfr_rnd_t @var{rnd}) 1470@deftypefunx int mpfr_add_z (mpfr_t @var{rop}, mpfr_t @var{op1}, mpz_t @var{op2}, mpfr_rnd_t @var{rnd}) 1471@deftypefunx int mpfr_add_q (mpfr_t @var{rop}, mpfr_t @var{op1}, mpq_t @var{op2}, mpfr_rnd_t @var{rnd}) 1472Set @var{rop} to @math{@var{op1} + @var{op2}} rounded in the direction 1473@var{rnd}. For types having no signed zero, it is considered unsigned 1474(i.e., (+0) + 0 = (+0) and (@minus{}0) + 0 = (@minus{}0)). 1475The @code{mpfr_add_d} function assumes that the radix of the @code{double} type 1476is a power of 2, with a precision at most that declared by the C implementation 1477(macro @code{IEEE_DBL_MANT_DIG}, and if not defined 53 bits). 1478@end deftypefun 1479 1480@deftypefun int mpfr_sub (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1481@deftypefunx int mpfr_ui_sub (mpfr_t @var{rop}, unsigned long int @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1482@deftypefunx int mpfr_sub_ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mpfr_rnd_t @var{rnd}) 1483@deftypefunx int mpfr_si_sub (mpfr_t @var{rop}, long int @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1484@deftypefunx int mpfr_sub_si (mpfr_t @var{rop}, mpfr_t @var{op1}, long int @var{op2}, mpfr_rnd_t @var{rnd}) 1485@deftypefunx int mpfr_d_sub (mpfr_t @var{rop}, double @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1486@deftypefunx int mpfr_sub_d (mpfr_t @var{rop}, mpfr_t @var{op1}, double @var{op2}, mpfr_rnd_t @var{rnd}) 1487@deftypefunx int mpfr_sub_z (mpfr_t @var{rop}, mpfr_t @var{op1}, mpz_t @var{op2}, mpfr_rnd_t @var{rnd}) 1488@deftypefunx int mpfr_sub_q (mpfr_t @var{rop}, mpfr_t @var{op1}, mpq_t @var{op2}, mpfr_rnd_t @var{rnd}) 1489Set @var{rop} to @math{@var{op1} - @var{op2}} rounded in the direction 1490@var{rnd}. For types having no signed zero, it is considered unsigned 1491(i.e., (+0) @minus{} 0 = (+0), (@minus{}0) @minus{} 0 = (@minus{}0), 14920 @minus{} (+0) = (@minus{}0) and 0 @minus{} (@minus{}0) = (+0)). 1493The same restrictions than for @code{mpfr_add_d} apply to @code{mpfr_d_sub} 1494and @code{mpfr_sub_d}. 1495@end deftypefun 1496 1497@deftypefun int mpfr_mul (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1498@deftypefunx int mpfr_mul_ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mpfr_rnd_t @var{rnd}) 1499@deftypefunx int mpfr_mul_si (mpfr_t @var{rop}, mpfr_t @var{op1}, long int @var{op2}, mpfr_rnd_t @var{rnd}) 1500@deftypefunx int mpfr_mul_d (mpfr_t @var{rop}, mpfr_t @var{op1}, double @var{op2}, mpfr_rnd_t @var{rnd}) 1501@deftypefunx int mpfr_mul_z (mpfr_t @var{rop}, mpfr_t @var{op1}, mpz_t @var{op2}, mpfr_rnd_t @var{rnd}) 1502@deftypefunx int mpfr_mul_q (mpfr_t @var{rop}, mpfr_t @var{op1}, mpq_t @var{op2}, mpfr_rnd_t @var{rnd}) 1503Set @var{rop} to @math{@var{op1} @GMPtimes{} @var{op2}} rounded in the 1504direction @var{rnd}. 1505When a result is zero, its sign is the product of the signs of the operands 1506(for types having no signed zero, it is considered positive). 1507The same restrictions than for @code{mpfr_add_d} apply to @code{mpfr_mul_d}. 1508@end deftypefun 1509 1510@deftypefun int mpfr_sqr (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1511Set @var{rop} to @m{@var{op}^{2}, the square of @var{op}} 1512rounded in the direction @var{rnd}. 1513@end deftypefun 1514 1515@deftypefun int mpfr_div (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1516@deftypefunx int mpfr_ui_div (mpfr_t @var{rop}, unsigned long int @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1517@deftypefunx int mpfr_div_ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mpfr_rnd_t @var{rnd}) 1518@deftypefunx int mpfr_si_div (mpfr_t @var{rop}, long int @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1519@deftypefunx int mpfr_div_si (mpfr_t @var{rop}, mpfr_t @var{op1}, long int @var{op2}, mpfr_rnd_t @var{rnd}) 1520@deftypefunx int mpfr_d_div (mpfr_t @var{rop}, double @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1521@deftypefunx int mpfr_div_d (mpfr_t @var{rop}, mpfr_t @var{op1}, double @var{op2}, mpfr_rnd_t @var{rnd}) 1522@deftypefunx int mpfr_div_z (mpfr_t @var{rop}, mpfr_t @var{op1}, mpz_t @var{op2}, mpfr_rnd_t @var{rnd}) 1523@deftypefunx int mpfr_div_q (mpfr_t @var{rop}, mpfr_t @var{op1}, mpq_t @var{op2}, mpfr_rnd_t @var{rnd}) 1524Set @var{rop} to @math{@var{op1}/@var{op2}} rounded in the direction @var{rnd}. 1525When a result is zero, its sign is the product of the signs of the operands 1526(for types having no signed zero, it is considered positive). 1527The same restrictions than for @code{mpfr_add_d} apply to @code{mpfr_d_div} 1528and @code{mpfr_div_d}. 1529@end deftypefun 1530 1531@deftypefun int mpfr_sqrt (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1532@deftypefunx int mpfr_sqrt_ui (mpfr_t @var{rop}, unsigned long int @var{op}, mpfr_rnd_t @var{rnd}) 1533Set @var{rop} to @m{\sqrt{@var{op}}, the square root of @var{op}} 1534rounded in the direction @var{rnd} (set @var{rop} to @minus{}0 if @var{op} is 1535@minus{}0, to be consistent with the IEEE 754 standard). 1536Set @var{rop} to NaN if @var{op} is negative. 1537@end deftypefun 1538 1539@deftypefun int mpfr_rec_sqrt (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1540Set @var{rop} to @m{1/\sqrt{@var{op}}, the reciprocal square root of @var{op}} 1541rounded in the direction @var{rnd}. Set @var{rop} to +Inf if @var{op} is 1542@pom{}0, +0 if @var{op} is +Inf, and NaN if @var{op} is negative. 1543@end deftypefun 1544 1545@deftypefun int mpfr_cbrt (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1546@deftypefunx int mpfr_root (mpfr_t @var{rop}, mpfr_t @var{op}, unsigned long int @var{k}, mpfr_rnd_t @var{rnd}) 1547Set @var{rop} to the cubic root (resp.@: the @var{k}th root) 1548of @var{op} rounded in the direction @var{rnd}. 1549For @var{k} odd (resp.@: even) and @var{op} negative (including @minus{}Inf), 1550set @var{rop} to a negative number (resp.@: NaN). 1551The @var{k}th root of @minus{}0 is defined to be @minus{}0, 1552whatever the parity of @var{k}. 1553@end deftypefun 1554 1555@deftypefun int mpfr_pow (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1556@deftypefunx int mpfr_pow_ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mpfr_rnd_t @var{rnd}) 1557@deftypefunx int mpfr_pow_si (mpfr_t @var{rop}, mpfr_t @var{op1}, long int @var{op2}, mpfr_rnd_t @var{rnd}) 1558@deftypefunx int mpfr_pow_z (mpfr_t @var{rop}, mpfr_t @var{op1}, mpz_t @var{op2}, mpfr_rnd_t @var{rnd}) 1559@deftypefunx int mpfr_ui_pow_ui (mpfr_t @var{rop}, unsigned long int @var{op1}, unsigned long int @var{op2}, mpfr_rnd_t @var{rnd}) 1560@deftypefunx int mpfr_ui_pow (mpfr_t @var{rop}, unsigned long int @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1561Set @var{rop} to @m{@var{op1}^{op2}, @var{op1} raised to @var{op2}}, 1562rounded in the direction @var{rnd}. 1563Special values are handled as described in the ISO C99 and IEEE 754-2008 1564standards for the @code{pow} function: 1565@itemize @bullet 1566@item @code{pow(@pom{}0, @var{y})} returns plus or minus infinity for @var{y} a negative odd integer. 1567@item @code{pow(@pom{}0, @var{y})} returns plus infinity for @var{y} negative and not an odd integer. 1568@item @code{pow(@pom{}0, @var{y})} returns plus or minus zero for @var{y} a positive odd integer. 1569@item @code{pow(@pom{}0, @var{y})} returns plus zero for @var{y} positive and not an odd integer. 1570@item @code{pow(-1, @pom{}Inf)} returns 1. 1571@item @code{pow(+1, @var{y})} returns 1 for any @var{y}, even a NaN. 1572@item @code{pow(@var{x}, @pom{}0)} returns 1 for any @var{x}, even a NaN. 1573@item @code{pow(@var{x}, @var{y})} returns NaN for finite negative @var{x} and finite non-integer @var{y}. 1574@item @code{pow(@var{x}, -Inf)} returns plus infinity for @math{0 < @GMPabs{x} < 1}, and plus zero for @math{@GMPabs{x} > 1}. 1575@item @code{pow(@var{x}, +Inf)} returns plus zero for @math{0 < @GMPabs{x} < 1}, and plus infinity for @math{@GMPabs{x} > 1}. 1576@item @code{pow(-Inf, @var{y})} returns minus zero for @var{y} a negative odd integer. 1577@item @code{pow(-Inf, @var{y})} returns plus zero for @var{y} negative and not an odd integer. 1578@item @code{pow(-Inf, @var{y})} returns minus infinity for @var{y} a positive odd integer. 1579@item @code{pow(-Inf, @var{y})} returns plus infinity for @var{y} positive and not an odd integer. 1580@item @code{pow(+Inf, @var{y})} returns plus zero for @var{y} negative, and plus infinity for @var{y} positive. 1581@end itemize 1582@end deftypefun 1583 1584@deftypefun int mpfr_neg (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1585@deftypefunx int mpfr_abs (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1586Set @var{rop} to @math{-@var{op}} and the absolute value of @var{op} 1587respectively, rounded in the direction @var{rnd}. 1588Just changes or adjusts 1589the sign if @var{rop} and @var{op} are the same variable, 1590otherwise a rounding might occur if the precision of @var{rop} is less than 1591that of @var{op}. 1592@end deftypefun 1593 1594@deftypefun int mpfr_dim (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1595Set @var{rop} to the positive difference of @var{op1} and @var{op2}, i.e., 1596@math{@var{op1} - @var{op2}} rounded in the direction @var{rnd} 1597if @math{@var{op1} > @var{op2}}, +0 if @math{@var{op1} @le{} @var{op2}}, 1598and NaN if @var{op1} or @var{op2} is NaN. 1599@end deftypefun 1600 1601@deftypefun int mpfr_mul_2ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mpfr_rnd_t @var{rnd}) 1602@deftypefunx int mpfr_mul_2si (mpfr_t @var{rop}, mpfr_t @var{op1}, long int @var{op2}, mpfr_rnd_t @var{rnd}) 1603Set @var{rop} to @m{@var{op1} \times 2^{op2}, @var{op1} times 2 raised 1604to @var{op2}} 1605rounded in the direction @var{rnd}. Just increases the exponent by @var{op2} 1606when @var{rop} and @var{op1} are identical. 1607@end deftypefun 1608 1609@deftypefun int mpfr_div_2ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mpfr_rnd_t @var{rnd}) 1610@deftypefunx int mpfr_div_2si (mpfr_t @var{rop}, mpfr_t @var{op1}, long int @var{op2}, mpfr_rnd_t @var{rnd}) 1611Set @var{rop} to @m{@var{op1}/2^{op2}, @var{op1} divided by 2 raised 1612to @var{op2}} 1613rounded in the direction @var{rnd}. Just decreases the exponent by @var{op2} 1614when @var{rop} and @var{op1} are identical. 1615@end deftypefun 1616 1617@node Comparison Functions, Special Functions, Basic Arithmetic Functions, MPFR Interface 1618@comment node-name, next, previous, up 1619@cindex Float comparisons functions 1620@cindex Comparison functions 1621@section Comparison Functions 1622 1623@deftypefun int mpfr_cmp (mpfr_t @var{op1}, mpfr_t @var{op2}) 1624@deftypefunx int mpfr_cmp_ui (mpfr_t @var{op1}, unsigned long int @var{op2}) 1625@deftypefunx int mpfr_cmp_si (mpfr_t @var{op1}, long int @var{op2}) 1626@deftypefunx int mpfr_cmp_d (mpfr_t @var{op1}, double @var{op2}) 1627@deftypefunx int mpfr_cmp_ld (mpfr_t @var{op1}, long double @var{op2}) 1628@deftypefunx int mpfr_cmp_z (mpfr_t @var{op1}, mpz_t @var{op2}) 1629@deftypefunx int mpfr_cmp_q (mpfr_t @var{op1}, mpq_t @var{op2}) 1630@deftypefunx int mpfr_cmp_f (mpfr_t @var{op1}, mpf_t @var{op2}) 1631Compare @var{op1} and @var{op2}. Return a positive value if @math{@var{op1} > 1632@var{op2}}, zero if @math{@var{op1} = @var{op2}}, and a negative value if 1633@math{@var{op1} < @var{op2}}. 1634Both @var{op1} and @var{op2} are considered to their full own precision, 1635which may differ. 1636If one of the operands is NaN, set the @emph{erange} flag and return zero. 1637 1638Note: These functions may be useful to distinguish the three possible cases. 1639If you need to distinguish two cases only, it is recommended to use the 1640predicate functions (e.g., @code{mpfr_equal_p} for the equality) described 1641below; they behave like the IEEE 754 comparisons, in particular when one 1642or both arguments are NaN. But only floating-point numbers can be compared 1643(you may need to do a conversion first). 1644@end deftypefun 1645 1646@deftypefun int mpfr_cmp_ui_2exp (mpfr_t @var{op1}, unsigned long int @var{op2}, mpfr_exp_t @var{e}) 1647@deftypefunx int mpfr_cmp_si_2exp (mpfr_t @var{op1}, long int @var{op2}, mpfr_exp_t @var{e}) 1648Compare @var{op1} and @m{@var{op2} \times 2^e, @var{op2} multiplied by two to 1649the power @var{e}}. Similar as above. 1650@end deftypefun 1651 1652@deftypefun int mpfr_cmpabs (mpfr_t @var{op1}, mpfr_t @var{op2}) 1653Compare @math{|@var{op1}|} and @math{|@var{op2}|}. Return a positive value if 1654@math{|@var{op1}| > |@var{op2}|}, zero if @math{|@var{op1}| = |@var{op2}|}, and 1655a negative value if @math{|@var{op1}| < |@var{op2}|}. 1656If one of the operands is NaN, set the @emph{erange} flag and return zero. 1657@end deftypefun 1658 1659@deftypefun int mpfr_nan_p (mpfr_t @var{op}) 1660@deftypefunx int mpfr_inf_p (mpfr_t @var{op}) 1661@deftypefunx int mpfr_number_p (mpfr_t @var{op}) 1662@deftypefunx int mpfr_zero_p (mpfr_t @var{op}) 1663@deftypefunx int mpfr_regular_p (mpfr_t @var{op}) 1664Return non-zero if @var{op} is respectively NaN, an infinity, an ordinary 1665number (i.e., neither NaN nor an infinity), zero, or a regular number 1666(i.e., neither NaN, nor an infinity nor zero). Return zero otherwise. 1667@end deftypefun 1668 1669@deftypefn Macro int mpfr_sgn (mpfr_t @var{op}) 1670Return a positive value if @math{@var{op} > 0}, zero if @math{@var{op} = 0}, 1671and a negative value if @math{@var{op} < 0}. 1672If the operand is NaN, set the @emph{erange} flag and return zero. 1673This is equivalent to @code{mpfr_cmp_ui (op, 0)}, but more efficient. 1674@end deftypefn 1675 1676@deftypefun int mpfr_greater_p (mpfr_t @var{op1}, mpfr_t @var{op2}) 1677@deftypefunx int mpfr_greaterequal_p (mpfr_t @var{op1}, mpfr_t @var{op2}) 1678@deftypefunx int mpfr_less_p (mpfr_t @var{op1}, mpfr_t @var{op2}) 1679@deftypefunx int mpfr_lessequal_p (mpfr_t @var{op1}, mpfr_t @var{op2}) 1680@deftypefunx int mpfr_equal_p (mpfr_t @var{op1}, mpfr_t @var{op2}) 1681Return non-zero if 1682@math{@var{op1} > @var{op2}}, 1683@math{@var{op1} @ge{} @var{op2}}, 1684@math{@var{op1} < @var{op2}}, 1685@math{@var{op1} @le{} @var{op2}}, 1686@math{@var{op1} = @var{op2}} respectively, 1687and zero otherwise. 1688Those functions return zero whenever @var{op1} and/or @var{op2} is NaN. 1689@end deftypefun 1690 1691@deftypefun int mpfr_lessgreater_p (mpfr_t @var{op1}, mpfr_t @var{op2}) 1692Return non-zero if @math{@var{op1} < @var{op2}} or 1693@math{@var{op1} > @var{op2}} (i.e., neither @var{op1}, nor @var{op2} is 1694NaN, and @math{@var{op1} @ne{} @var{op2}}), zero otherwise (i.e., @var{op1} 1695and/or @var{op2} is NaN, or @math{@var{op1} = @var{op2}}). 1696@end deftypefun 1697 1698@deftypefun int mpfr_unordered_p (mpfr_t @var{op1}, mpfr_t @var{op2}) 1699Return non-zero if @var{op1} or @var{op2} is a NaN (i.e., they cannot be 1700compared), zero otherwise. 1701@end deftypefun 1702 1703@node Special Functions, Input and Output Functions, Comparison Functions, MPFR Interface 1704@cindex Special functions 1705@section Special Functions 1706 1707All those functions, except explicitly stated (for example 1708@code{mpfr_sin_cos}), return a ternary value as defined in Section 1709``Rounding Modes'', i.e., zero for an 1710exact return value, a positive value for a return value larger than the 1711exact result, and a negative value otherwise. 1712 1713Important note: in some domains, computing special functions (either with 1714correct or incorrect rounding) is expensive, even for small precision, 1715for example the trigonometric and Bessel functions for large argument. 1716 1717@deftypefun int mpfr_log (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1718@deftypefunx int mpfr_log2 (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1719@deftypefunx int mpfr_log10 (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1720Set @var{rop} to the natural logarithm of @var{op}, 1721@m{\log_2 @var{op}, log2(@var{op})} or 1722@m{\log_{10} @var{op}, log10(@var{op})}, respectively, 1723rounded in the direction @var{rnd}. 1724Set @var{rop} to @minus{}Inf if @var{op} is @minus{}0 1725(i.e., the sign of the zero has no influence on the result). 1726@end deftypefun 1727 1728@deftypefun int mpfr_exp (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1729@deftypefunx int mpfr_exp2 (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1730@deftypefunx int mpfr_exp10 (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1731Set @var{rop} to the exponential of @var{op}, 1732 to @m{2^{op}, 2 power of @var{op}} 1733or to @m{10^{op}, 10 power of @var{op}}, respectively, 1734rounded in the direction @var{rnd}. 1735@end deftypefun 1736 1737@deftypefun int mpfr_cos (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1738@deftypefunx int mpfr_sin (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1739@deftypefunx int mpfr_tan (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1740Set @var{rop} to the cosine of @var{op}, sine of @var{op}, 1741tangent of @var{op}, rounded in the direction @var{rnd}. 1742@end deftypefun 1743 1744@deftypefun int mpfr_sin_cos (mpfr_t @var{sop}, mpfr_t @var{cop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1745Set simultaneously @var{sop} to the sine of @var{op} and @var{cop} to the 1746cosine of @var{op}, rounded in the direction @var{rnd} with the corresponding 1747precisions of @var{sop} and @var{cop}, which must be different variables. 1748Return 0 iff both results are exact, more precisely it returns @math{s+4c} 1749where @math{s=0} if @var{sop} is exact, @math{s=1} if @var{sop} is larger 1750than the sine of @var{op}, @math{s=2} if @var{sop} is smaller than the sine 1751of @var{op}, and similarly for @math{c} and the cosine of @var{op}. 1752@end deftypefun 1753 1754@deftypefun int mpfr_sec (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1755@deftypefunx int mpfr_csc (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1756@deftypefunx int mpfr_cot (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1757Set @var{rop} to the secant of @var{op}, cosecant of @var{op}, 1758cotangent of @var{op}, rounded in the direction @var{rnd}. 1759@end deftypefun 1760 1761@deftypefun int mpfr_acos (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1762@deftypefunx int mpfr_asin (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1763@deftypefunx int mpfr_atan (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1764Set @var{rop} to the arc-cosine, arc-sine or arc-tangent of @var{op}, 1765rounded in the direction @var{rnd}. 1766Note that since @code{acos(-1)} returns the floating-point number closest to 1767@m{\pi,Pi} according to the given rounding mode, this number might not be 1768in the output range @math{0 @le{} @var{rop} < \pi} 1769of the arc-cosine function; 1770still, the result lies in the image of the output range 1771by the rounding function. 1772The same holds for @code{asin(-1)}, @code{asin(1)}, @code{atan(-Inf)}, 1773@code{atan(+Inf)} or for @code{atan(op)} with large @var{op} and 1774small precision of @var{rop}. 1775@c PZ: check the above is correct 1776@end deftypefun 1777 1778@deftypefun int mpfr_atan2 (mpfr_t @var{rop}, mpfr_t @var{y}, mpfr_t @var{x}, mpfr_rnd_t @var{rnd}) 1779Set @var{rop} to the arc-tangent2 of @var{y} and @var{x}, 1780rounded in the direction @var{rnd}: 1781if @code{x > 0}, @code{atan2(y, x) = atan (y/x)}; 1782if @code{x < 0}, @code{atan2(y, x) = sign(y)*(Pi - atan (@GMPabs{y/x}))}, 1783thus a number from @m{-\pi,-Pi} to @m{\pi,Pi}. 1784As for @code{atan}, in case the exact mathematical result is @m{+\pi,+Pi} or 1785@m{-\pi,-Pi}, 1786its rounded result might be outside the function output range. 1787 1788@code{atan2(y, 0)} does not raise any floating-point exception. 1789Special values are handled as described in the ISO C99 and IEEE 754-2008 1790standards for the @code{atan2} function: 1791@itemize @bullet 1792@item @code{atan2(+0, -0)} returns @m{+\pi,+Pi}. 1793@item @code{atan2(-0, -0)} returns @m{-\pi,-Pi}. 1794@item @code{atan2(+0, +0)} returns +0. 1795@item @code{atan2(-0, +0)} returns @minus{}0. 1796@item @code{atan2(+0, x)} returns @m{+\pi,+Pi} for @math{x < 0}. 1797@item @code{atan2(-0, x)} returns @m{-\pi,-Pi} for @math{x < 0}. 1798@item @code{atan2(+0, x)} returns +0 for @math{x > 0}. 1799@item @code{atan2(-0, x)} returns @minus{}0 for @math{x > 0}. 1800@item @code{atan2(y, 0)} returns @m{-\pi/2,-Pi/2} for @math{y < 0}. 1801@item @code{atan2(y, 0)} returns @m{+\pi/2,+Pi/2} for @math{y > 0}. 1802@item @code{atan2(+Inf, -Inf)} returns @m{+3\pi/4,+3*Pi/4}. 1803@item @code{atan2(-Inf, -Inf)} returns @m{-3\pi/4,-3*Pi/4}. 1804@item @code{atan2(+Inf, +Inf)} returns @m{+\pi/4,+Pi/4}. 1805@item @code{atan2(-Inf, +Inf)} returns @m{-\pi/4,-Pi/4}. 1806@item @code{atan2(+Inf, x)} returns @m{+\pi/2,+Pi/2} for finite @math{x}. 1807@item @code{atan2(-Inf, x)} returns @m{-\pi/2,-Pi/2} for finite @math{x}. 1808@item @code{atan2(y, -Inf)} returns @m{+\pi,+Pi} for finite @math{y > 0}. 1809@item @code{atan2(y, -Inf)} returns @m{-\pi,-Pi} for finite @math{y < 0}. 1810@item @code{atan2(y, +Inf)} returns +0 for finite @math{y > 0}. 1811@item @code{atan2(y, +Inf)} returns @minus{}0 for finite @math{y < 0}. 1812@end itemize 1813@end deftypefun 1814 1815@deftypefun int mpfr_cosh (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1816@deftypefunx int mpfr_sinh (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1817@deftypefunx int mpfr_tanh (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1818Set @var{rop} to the hyperbolic cosine, sine or tangent of @var{op}, 1819rounded in the direction @var{rnd}. 1820@end deftypefun 1821 1822@deftypefun int mpfr_sinh_cosh (mpfr_t @var{sop}, mpfr_t @var{cop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1823Set simultaneously @var{sop} to the hyperbolic sine of @var{op} and 1824@var{cop} to the hyperbolic cosine of @var{op}, 1825rounded in the direction @var{rnd} with the corresponding precision of 1826@var{sop} and @var{cop}, which must be different variables. 1827Return 0 iff both results are exact (see @code{mpfr_sin_cos} for a more 1828detailed description of the return value). 1829@end deftypefun 1830 1831@deftypefun int mpfr_sech (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1832@deftypefunx int mpfr_csch (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1833@deftypefunx int mpfr_coth (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1834Set @var{rop} to the hyperbolic secant of @var{op}, cosecant of @var{op}, 1835cotangent of @var{op}, rounded in the direction @var{rnd}. 1836@end deftypefun 1837 1838@deftypefun int mpfr_acosh (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1839@deftypefunx int mpfr_asinh (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1840@deftypefunx int mpfr_atanh (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1841Set @var{rop} to the inverse hyperbolic cosine, sine or tangent of @var{op}, 1842rounded in the direction @var{rnd}. 1843@end deftypefun 1844 1845@deftypefun int mpfr_fac_ui (mpfr_t @var{rop}, unsigned long int @var{op}, mpfr_rnd_t @var{rnd}) 1846Set @var{rop} to the factorial of @var{op}, rounded in the direction @var{rnd}. 1847@end deftypefun 1848 1849@deftypefun int mpfr_log1p (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1850Set @var{rop} to the logarithm of one plus @var{op}, 1851rounded in the direction @var{rnd}. 1852@end deftypefun 1853 1854@deftypefun int mpfr_expm1 (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1855Set @var{rop} to @m{e^{op}-1,the exponential of @var{op} followed by a 1856subtraction by one}, rounded in the direction @var{rnd}. 1857@end deftypefun 1858 1859@deftypefun int mpfr_eint (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1860Set @var{rop} to the exponential integral of @var{op}, 1861rounded in the direction @var{rnd}. 1862For positive @var{op}, 1863the exponential integral is the sum of Euler's constant, of the logarithm 1864of @var{op}, and of the sum for k from 1 to infinity of 1865@ifnottex 1866@var{op} to the power k, divided by k and factorial(k). 1867@end ifnottex 1868@tex 1869$@var{op}^k/(k \cdot k!)$. 1870@end tex 1871For negative @var{op}, @var{rop} is set to NaN. 1872@end deftypefun 1873 1874@deftypefun int mpfr_li2 (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1875Set @var{rop} to real part of the dilogarithm of @var{op}, rounded in the 1876direction @var{rnd}. MPFR defines the dilogarithm function as 1877@m{-\int_{t=0}^{op} \log(1-t)/t\ dt,the integral of -log(1-t)/t from 0 1878to @var{op}}. 1879@c FIXME: It should be {@var{op}} instead of {op} above, but pdftex fails 1880@c on the correct form. 1881@end deftypefun 1882 1883@deftypefun int mpfr_gamma (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1884Set @var{rop} to the value of the Gamma function on @var{op}, rounded in the 1885direction @var{rnd}. When @var{op} is a negative integer, @var{rop} is set 1886to NaN. 1887@end deftypefun 1888 1889@deftypefun int mpfr_lngamma (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1890Set @var{rop} to the value of the logarithm of the Gamma function on @var{op}, 1891rounded in the direction @var{rnd}. 1892When @math{@minus{}2@var{k}@minus{}1 @le{} @var{op} @le{} @minus{}2@var{k}}, 1893@var{k} being a non-negative integer, @var{rop} is set to NaN. 1894See also @code{mpfr_lgamma}. 1895@end deftypefun 1896 1897@deftypefun int mpfr_lgamma (mpfr_t @var{rop}, int *@var{signp}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1898Set @var{rop} to the value of the logarithm of the absolute value of the 1899Gamma function on @var{op}, rounded in the direction @var{rnd}. The sign 1900(1 or @minus{}1) of Gamma(@var{op}) is returned in the object pointed to 1901by @var{signp}. When @var{op} is an infinity or a non-positive integer, set 1902@var{rop} to +Inf. When @var{op} is NaN, @minus{}Inf or a negative integer, 1903*@var{signp} is undefined, and when @var{op} is @pom{}0, *@var{signp} is 1904the sign of the zero. 1905@end deftypefun 1906 1907@deftypefun int mpfr_digamma (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1908Set @var{rop} to the value of the Digamma (sometimes also called Psi) 1909function on @var{op}, rounded in the direction @var{rnd}. 1910When @var{op} is a negative integer, set @var{rop} to NaN. 1911@end deftypefun 1912 1913@deftypefun int mpfr_zeta (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1914@deftypefunx int mpfr_zeta_ui (mpfr_t @var{rop}, unsigned long @var{op}, mpfr_rnd_t @var{rnd}) 1915Set @var{rop} to the value of the Riemann Zeta function on @var{op}, 1916rounded in the direction @var{rnd}. 1917@end deftypefun 1918 1919@deftypefun int mpfr_erf (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1920@deftypefunx int mpfr_erfc (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1921Set @var{rop} to the value of the error function on @var{op} 1922(resp.@: the complementary error function on @var{op}) 1923rounded in the direction @var{rnd}. 1924@end deftypefun 1925 1926@deftypefun int mpfr_j0 (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1927@deftypefunx int mpfr_j1 (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1928@deftypefunx int mpfr_jn (mpfr_t @var{rop}, long @var{n}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1929Set @var{rop} to the value of the first kind Bessel function of order 0, 1930(resp.@: 1 and @var{n}) 1931on @var{op}, rounded in the direction @var{rnd}. When @var{op} is 1932NaN, @var{rop} is always set to NaN. When @var{op} is plus or minus Infinity, 1933@var{rop} is set to +0. When @var{op} is zero, and @var{n} is not zero, 1934@var{rop} is set to +0 or @minus{}0 depending on the parity and sign of @var{n}, 1935and the sign of @var{op}. 1936@end deftypefun 1937 1938@deftypefun int mpfr_y0 (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1939@deftypefunx int mpfr_y1 (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1940@deftypefunx int mpfr_yn (mpfr_t @var{rop}, long @var{n}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 1941Set @var{rop} to the value of the second kind Bessel function of order 0 1942(resp.@: 1 and @var{n}) 1943on @var{op}, rounded in the direction @var{rnd}. When @var{op} is 1944NaN or negative, @var{rop} is always set to NaN. When @var{op} is +Inf, 1945@var{rop} is set to +0. When @var{op} is zero, @var{rop} is set to +Inf 1946or @minus{}Inf depending on the parity and sign of @var{n}. 1947@end deftypefun 1948 1949@deftypefun int mpfr_fma (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_t @var{op3}, mpfr_rnd_t @var{rnd}) 1950@deftypefunx int mpfr_fms (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_t @var{op3}, mpfr_rnd_t @var{rnd}) 1951Set @var{rop} to @math{(@var{op1} @GMPtimes{} @var{op2}) + @var{op3}} 1952(resp.@: @math{(@var{op1} @GMPtimes{} @var{op2}) - @var{op3}}) 1953rounded in the direction @var{rnd}. 1954@end deftypefun 1955 1956@deftypefun int mpfr_agm (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 1957Set @var{rop} to the arithmetic-geometric mean of @var{op1} and @var{op2}, 1958rounded in the direction @var{rnd}. 1959The arithmetic-geometric mean is the common limit of the sequences 1960@m{u_n,@var{u}_@var{n}} and @m{v_n,@var{v}_@var{n}}, 1961where @m{u_0,@var{u}_@var{0}}=@var{op1}, @m{v_0,@var{v}_@var{0}}=@var{op2}, 1962@m{u_{n+1},@var{u}_(@var{n}+1)} is the 1963arithmetic mean of @m{u_n,@var{u}_@var{n}} and @m{v_n,@var{v}_@var{n}}, 1964and @m{v_{n+1},@var{v}_(@var{n}+1)} is the geometric mean of 1965@m{u_n,@var{u}_@var{n}} and @m{v_n,@var{v}_@var{n}}. 1966If any operand is negative, set @var{rop} to NaN. 1967@end deftypefun 1968 1969@deftypefun int mpfr_hypot (mpfr_t @var{rop}, mpfr_t @var{x}, mpfr_t @var{y}, mpfr_rnd_t @var{rnd}) 1970Set @var{rop} to the Euclidean norm of @var{x} and @var{y}, 1971@ifnottex 1972i.e., the square root of the sum of the squares of @var{x} and @var{y}, 1973@end ifnottex 1974@tex 1975i.e., $\sqrt{x^2+y^2}$, 1976@end tex 1977rounded in the direction @var{rnd}. 1978Special values are handled as described in Section F.9.4.3 of 1979the ISO C99 and IEEE 754-2008 standards: 1980If @var{x} or @var{y} is an infinity, then +Inf is returned in @var{rop}, 1981even if the other number is NaN. 1982@end deftypefun 1983 1984@deftypefun int mpfr_ai (mpfr_t @var{rop}, mpfr_t @var{x}, mpfr_rnd_t @var{rnd}) 1985Set @var{rop} to the value of the Airy function Ai 1986 on @var{x}, rounded in the direction @var{rnd}. 1987When @var{x} is 1988NaN, 1989@var{rop} is always set to NaN. When @var{x} is +Inf or @minus{}Inf, 1990@var{rop} is +0. 1991The current implementation is not intended to be used with large arguments. 1992It works with @GMPabs{@var{x}} typically smaller than 500. For larger arguments, 1993other methods should be used and will be implemented in a future version. 1994@end deftypefun 1995 1996@deftypefun int mpfr_const_log2 (mpfr_t @var{rop}, mpfr_rnd_t @var{rnd}) 1997@deftypefunx int mpfr_const_pi (mpfr_t @var{rop}, mpfr_rnd_t @var{rnd}) 1998@deftypefunx int mpfr_const_euler (mpfr_t @var{rop}, mpfr_rnd_t @var{rnd}) 1999@deftypefunx int mpfr_const_catalan (mpfr_t @var{rop}, mpfr_rnd_t @var{rnd}) 2000Set @var{rop} to the logarithm of 2, the value of @m{\pi,Pi}, 2001of Euler's constant 0.577@dots{}, of Catalan's constant 0.915@dots{}, 2002respectively, rounded in the direction 2003@var{rnd}. These functions cache the computed values to avoid other 2004calculations if a lower or equal precision is requested. To free these caches, 2005use @code{mpfr_free_cache}. 2006@end deftypefun 2007 2008@deftypefun void mpfr_free_cache (void) 2009Free various caches used by MPFR internally, in particular the 2010caches used by the functions computing constants (@code{mpfr_const_log2}, 2011@code{mpfr_const_pi}, 2012@code{mpfr_const_euler} and @code{mpfr_const_catalan}). 2013You should call this function before terminating a thread, even if you did 2014not call these functions directly (they could have been called internally). 2015@end deftypefun 2016 2017@deftypefun int mpfr_sum (mpfr_t @var{rop}, mpfr_ptr const @var{tab}[], unsigned long int @var{n}, mpfr_rnd_t @var{rnd}) 2018Set @var{rop} to the sum of all elements of @var{tab}, whose size is @var{n}, 2019rounded in the direction @var{rnd}. Warning: for efficiency reasons, 2020@var{tab} is an array of pointers 2021to @code{mpfr_t}, not an array of @code{mpfr_t}. 2022If the returned @code{int} value is zero, @var{rop} is guaranteed to be the 2023exact sum; otherwise @var{rop} might be smaller than, equal to, or larger than 2024the exact sum (in accordance to the rounding mode). 2025However, @code{mpfr_sum} does guarantee the result is correctly rounded. 2026@end deftypefun 2027 2028@node Input and Output Functions, Formatted Output Functions, Special Functions, MPFR Interface 2029@comment node-name, next, previous, up 2030@cindex Float input and output functions 2031@cindex Input functions 2032@cindex Output functions 2033@cindex I/O functions 2034@section Input and Output Functions 2035 2036This section describes functions that perform input from an input/output 2037stream, and functions that output to an input/output stream. 2038Passing a null pointer for a @code{stream} to any of these functions will make 2039them read from @code{stdin} and write to @code{stdout}, respectively. 2040 2041When using any of these functions, you must include the @code{<stdio.h>} 2042standard header before @file{mpfr.h}, to allow @file{mpfr.h} to define 2043prototypes for these functions. 2044 2045@deftypefun size_t mpfr_out_str (FILE *@var{stream}, int @var{base}, size_t @var{n}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 2046Output @var{op} on stream @var{stream}, as a string of digits in 2047base @var{base}, rounded in the direction @var{rnd}. 2048The base may vary from 2 to 62. Print @var{n} significant digits exactly, 2049or if @var{n} is 0, enough digits so that @var{op} can be read back 2050exactly (see @code{mpfr_get_str}). 2051 2052In addition to the significant digits, a decimal point (defined by the 2053current locale) at the right of the 2054first digit and a trailing exponent in base 10, in the form @samp{eNNN}, 2055are printed. If @var{base} is greater than 10, @samp{@@} will be used 2056instead of @samp{e} as exponent delimiter. 2057 2058Return the number of characters written, or if an error occurred, return 0. 2059@end deftypefun 2060 2061@deftypefun size_t mpfr_inp_str (mpfr_t @var{rop}, FILE *@var{stream}, int @var{base}, mpfr_rnd_t @var{rnd}) 2062Input a string in base @var{base} from stream @var{stream}, 2063rounded in the direction @var{rnd}, and put the 2064read float in @var{rop}. 2065@c The argument @var{base} must be in the range 2 to 62. 2066 2067@c The string is of the form @samp{M@@N} or, if the 2068@c base is 10 or less, alternatively @samp{MeN} or @samp{MEN}, or, if the base 2069@c is 16, alternatively @samp{MpB} or @samp{MPB}. 2070@c @samp{M} is the significand in the specified base, @samp{N} is the exponent 2071@c written in decimal for the specified base, and in base 16, @samp{B} is the 2072@c binary exponent written in decimal (i.e., it indicates the power of 2 by 2073@c which the significand is to be scaled). 2074This function reads a word (defined as a sequence of characters between 2075whitespace) and parses it using @code{mpfr_set_str}. 2076See the documentation of @code{mpfr_strtofr} for a detailed description 2077of the valid string formats. 2078@c Special values can be read as follows (the case does not matter): 2079@c @code{@@NaN@@}, @code{@@Inf@@}, @code{+@@Inf@@} and @code{-@@Inf@@}, 2080@c possibly followed by other characters; if the base is smaller or equal 2081@c to 16, the following strings are accepted too: @code{NaN}, @code{Inf}, 2082@c @code{+Inf} and @code{-Inf}. 2083 2084Return the number of bytes read, or if an error occurred, return 0. 2085@end deftypefun 2086 2087@c @deftypefun void mpfr_inp_raw (mpfr_t @var{float}, FILE *@var{stream}) 2088@c Input from stdio stream @var{stream} in the format written by 2089@c @code{mpfr_out_raw}, and put the result in @var{float}. 2090@c @end deftypefun 2091 2092@node Formatted Output Functions, Integer Related Functions, Input and Output Functions, MPFR Interface 2093@comment node-name, next, previous, up 2094@cindex Float output functions 2095@cindex Output functions 2096@cindex I/O functions 2097@section Formatted Output Functions 2098 2099@subsection Requirements 2100The class of @code{mpfr_printf} functions provides formatted output in a 2101similar manner as the standard C @code{printf}. These functions are defined 2102only if your system supports ISO C variadic functions and the corresponding 2103argument access macros. 2104 2105When using any of these functions, you must include the @code{<stdio.h>} 2106standard header before @file{mpfr.h}, to allow @file{mpfr.h} to define 2107prototypes for these functions. 2108 2109@subsection Format String 2110The format specification accepted by @code{mpfr_printf} is an extension of the 2111@code{printf} one. The conversion specification is of the form: 2112@example 2113% [flags] [width] [.[precision]] [type] [rounding] conv 2114@end example 2115@samp{flags}, @samp{width}, and @samp{precision} have the same meaning as for 2116the standard @code{printf} (in particular, notice that the @samp{precision} is 2117related to the number of digits displayed in the base chosen by @samp{conv} 2118and not related to the internal precision of the @code{mpfr_t} variable). 2119@code{mpfr_printf} accepts the same @samp{type} specifiers as GMP (except the 2120non-standard and deprecated @samp{q}, use @samp{ll} instead), namely the 2121length modifiers defined in the C standard: 2122 2123@quotation 2124@multitable {(space)} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} 2125@item @samp{h} @tab @code{short} 2126@item @samp{hh} @tab @code{char} 2127@item @samp{j} @tab @code{intmax_t} or @code{uintmax_t} 2128@item @samp{l} @tab @code{long} or @code{wchar_t} 2129@item @samp{ll} @tab @code{long long} 2130@item @samp{L} @tab @code{long double} 2131@item @samp{t} @tab @code{ptrdiff_t} 2132@item @samp{z} @tab @code{size_t} 2133@end multitable 2134@end quotation 2135 2136and the @samp{type} specifiers defined in GMP plus @samp{R} and @samp{P} 2137specific to MPFR (the second column in the table below shows the type of the 2138argument read in the argument list and the kind of @samp{conv} specifier to 2139use after the @samp{type} specifier): 2140 2141@quotation 2142@multitable {(space)} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} 2143@item @samp{F} @tab @code{mpf_t}, float conversions 2144@item @samp{Q} @tab @code{mpq_t}, integer conversions 2145@item @samp{M} @tab @code{mp_limb_t}, integer conversions 2146@item @samp{N} @tab @code{mp_limb_t} array, integer conversions 2147@item @samp{Z} @tab @code{mpz_t}, integer conversions 2148 2149@item @samp{P} @tab @code{mpfr_prec_t}, integer conversions 2150@item @samp{R} @tab @code{mpfr_t}, float conversions 2151@end multitable 2152@end quotation 2153 2154The @samp{type} specifiers have the same restrictions as those 2155mentioned in the GMP documentation: 2156@ifinfo 2157@pxref{Formatted Output Strings,,, gmp.info,GNU MP}. 2158@end ifinfo 2159@ifnotinfo 2160see Section ``Formatted Output Strings'' in @cite{GNU MP}. 2161@end ifnotinfo 2162In particular, the @samp{type} specifiers (except @samp{R} and @samp{P}) are 2163supported only if they are supported by @code{gmp_printf} in your GMP build; 2164this implies that the standard specifiers, such as @samp{t}, must @emph{also} 2165be supported by your C library if you want to use them. 2166 2167The @samp{rounding} field is specific to @code{mpfr_t} arguments and should 2168not be used with other types. 2169 2170With conversion specification not involving @samp{P} and @samp{R} types, 2171@code{mpfr_printf} behaves exactly as @code{gmp_printf}. 2172 2173The @samp{P} type specifies that a following @samp{o}, @samp{u}, @samp{x}, or 2174@samp{X} conversion specifier applies to a @code{mpfr_prec_t} argument. 2175It is needed because the @code{mpfr_prec_t} type does not necessarily 2176correspond to an @code{unsigned int} or any fixed standard type. 2177The @samp{precision} field specifies the minimum number of digits to 2178appear. The default @samp{precision} is 1. 2179For example: 2180@example 2181mpfr_t x; 2182mpfr_prec_t p; 2183mpfr_init (x); 2184@dots{} 2185p = mpfr_get_prec (x); 2186mpfr_printf ("variable x with %Pu bits", p); 2187@end example 2188 2189The @samp{R} type specifies that a following @samp{a}, @samp{A}, @samp{b}, 2190@samp{e}, @samp{E}, @samp{f}, @samp{F}, @samp{g}, @samp{G}, or @samp{n} 2191conversion specifier applies to a @code{mpfr_t} argument. 2192The @samp{R} type can be followed by a @samp{rounding} specifier denoted by 2193one of the following characters: 2194 2195@quotation 2196@multitable {(space)} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} 2197@item @samp{U} @tab round toward plus infinity 2198@item @samp{D} @tab round toward minus infinity 2199@item @samp{Y} @tab round away from zero 2200@item @samp{Z} @tab round toward zero 2201@item @samp{N} @tab round to nearest 2202@item @samp{*} @tab rounding mode indicated by the @code{mpfr_rnd_t} argument 2203just before the corresponding @code{mpfr_t} variable. 2204@end multitable 2205@end quotation 2206 2207The default rounding mode is rounding to nearest. 2208The following three examples are equivalent: 2209@example 2210mpfr_t x; 2211mpfr_init (x); 2212@dots{} 2213mpfr_printf ("%.128Rf", x); 2214mpfr_printf ("%.128RNf", x); 2215mpfr_printf ("%.128R*f", MPFR_RNDN, x); 2216@end example 2217 2218Note that the rounding away from zero mode is specified with @samp{Y} 2219because ISO C reserves the @samp{A} specifier for hexadecimal output (see 2220below). 2221 2222The output @samp{conv} specifiers allowed with @code{mpfr_t} parameter are: 2223 2224@quotation 2225@multitable {(space)} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM} 2226@item @samp{a} @samp{A} @tab hex float, C99 style 2227@item @samp{b} @tab binary output 2228@item @samp{e} @samp{E} @tab scientific format float 2229@item @samp{f} @samp{F} @tab fixed point float 2230@item @samp{g} @samp{G} @tab fixed or scientific float 2231@end multitable 2232@end quotation 2233 2234The conversion specifier @samp{b} which displays the argument in binary is 2235specific to @code{mpfr_t} arguments and should not be used with other types. 2236Other conversion specifiers have the same meaning as for a @code{double} 2237argument. 2238 2239In case of non-decimal output, only the significand is written in the 2240specified base, the exponent is always displayed in decimal. 2241Special values are always displayed as @code{nan}, @code{-inf}, and @code{inf} 2242for @samp{a}, @samp{b}, @samp{e}, @samp{f}, and @samp{g} specifiers and 2243@code{NAN}, @code{-INF}, and @code{INF} for @samp{A}, @samp{E}, @samp{F}, and 2244@samp{G} specifiers. 2245 2246If the @samp{precision} field is not empty, the @code{mpfr_t} number is 2247rounded to the given precision in the direction specified by the rounding 2248mode. 2249If the precision is zero with rounding to nearest mode and one of the 2250following @samp{conv} specifiers: @samp{a}, @samp{A}, @samp{b}, @samp{e}, 2251@samp{E}, tie case is rounded to even when it lies between two consecutive 2252values at the 2253wanted precision which have the same exponent, otherwise, it is rounded away 2254from zero. 2255For instance, 85 is displayed as "8e+1" and 95 is displayed as "1e+2" with the 2256format specification @code{"%.0RNe"}. 2257This also applies when the @samp{g} (resp. @samp{G}) conversion specifier uses 2258the @samp{e} (resp. @samp{E}) style. 2259If the precision is set to a value greater than the maximum value for an 2260@code{int}, it will be silently reduced down to @code{INT_MAX}. 2261 2262If the @samp{precision} field is empty (as in @code{%Re} or @code{%.RE}) with 2263@samp{conv} specifier @samp{e} and @samp{E}, the number is displayed with 2264enough digits so that it can be read back exactly, assuming that the input and 2265output variables have the same precision and that the input and output 2266rounding modes are both rounding to nearest (as for @code{mpfr_get_str}). 2267The default precision for an empty @samp{precision} field with @samp{conv} 2268specifiers @samp{f}, @samp{F}, @samp{g}, and @samp{G} is 6. 2269 2270 2271@subsection Functions 2272 2273For all the following functions, if the number of characters which ought to be 2274written appears to exceed the maximum limit for an @code{int}, nothing is 2275written in the stream (resp.@: to @code{stdout}, to @var{buf}, to @var{str}), 2276the function returns @minus{}1, sets the @emph{erange} flag, and (in 2277POSIX system only) @code{errno} is set to @code{EOVERFLOW}. 2278 2279@deftypefun int mpfr_fprintf (FILE *@var{stream}, const char *@var{template}, @dots{}) 2280@deftypefunx int mpfr_vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap}) 2281Print to the stream @var{stream} the optional arguments under the control of 2282the template string @var{template}. 2283Return the number of characters written or a negative value if an error 2284occurred. 2285@c If the number of characters which ought to be written appears 2286@c to exceed the maximum limit for an @code{int}, nothing is written in the 2287@c stream, the function returns @minus{}1, sets the @emph{erange} flag, and (in 2288@c POSIX system only) @code{errno} is set to @code{EOVERFLOW}. 2289@end deftypefun 2290 2291@deftypefun int mpfr_printf (const char *@var{template}, @dots{}) 2292@deftypefunx int mpfr_vprintf (const char *@var{template}, va_list @var{ap}) 2293Print to @code{stdout} the optional arguments under the control of the 2294template string @var{template}. 2295Return the number of characters written or a negative value if an error 2296occurred. 2297@c If the number of characters which ought to be written appears 2298@c to exceed the maximum limit for an @code{int}, nothing is written in 2299@c @code{stdout}, the function returns @minus{}1, sets the @emph{erange} flag, 2300@c and (in POSIX system only) @code{errno} is set to @code{EOVERFLOW}. 2301@end deftypefun 2302 2303@deftypefun int mpfr_sprintf (char *@var{buf}, const char *@var{template}, @dots{}) 2304@deftypefunx int mpfr_vsprintf (char *@var{buf}, const char *@var{template}, va_list @var{ap}) 2305Form a null-terminated string corresponding to the optional arguments under 2306the control of the template string @var{template}, and print it in 2307@var{buf}. No overlap is permitted between 2308@var{buf} and the other arguments. 2309Return the number of characters written in the array @var{buf} 2310@emph{not counting} 2311the terminating null character or a negative value if an error occurred. 2312@c If the number of characters which ought to be written appears to exceed the 2313@c maximum limit for an @code{int}, nothing is written in @var{buf}, the function 2314@c returns @minus{}1, sets the @emph{erange} flag, and (in POSIX system only) 2315@c code{errno} is set to @code{EOVERFLOW}. 2316@end deftypefun 2317 2318@deftypefun int mpfr_snprintf (char *@var{buf}, size_t @var{n}, const char *@var{template}, @dots{}) 2319@deftypefunx int mpfr_vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{template}, va_list @var{ap}) 2320Form a null-terminated string corresponding to the optional arguments under 2321the control of the template string @var{template}, and print it in 2322@var{buf}. If @var{n} is zero, nothing is 2323written and @var{buf} may be a null pointer, otherwise, the @var{n}@minus{}1 2324first characters are written in @var{buf} and the @var{n}-th is a null character. 2325Return the number of characters that would have been written had @var{n} be 2326sufficiently large, @emph{not counting} 2327the terminating null character, or a negative value if an error occurred. 2328@c If the number of characters produced by the 2329@c optional arguments under the control of the template string @var{template} 2330@c appears to exceed the maximum limit for an @code{int}, nothing is written in 2331@c @var{buf}, the function returns @minus{}1, sets the @emph{erange} flag, and 2332@c (in POSIX system only) @code{errno} is set to @code{EOVERFLOW}. 2333@end deftypefun 2334 2335@deftypefun int mpfr_asprintf (char **@var{str}, const char *@var{template}, @dots{}) 2336@deftypefunx int mpfr_vasprintf (char **@var{str}, const char *@var{template}, va_list @var{ap}) 2337Write their output as a null terminated string in a block of memory allocated 2338using the current allocation function. A pointer to the block is stored in 2339@var{str}. The block of memory must be freed using @code{mpfr_free_str}. 2340The return value is the number of characters written in the string, excluding 2341the null-terminator, or a negative value if an error occurred. 2342@c If the number of 2343@c characters produced by the optional arguments under the control of the 2344@c template string @var{template} appears to exceed the maximum limit for an 2345@c @code{int}, @var{str} is a null pointer, the function returns @minus{}1, sets 2346@c the @emph{erange} flag, and (in POSIX system only) @code{errno} is set to 2347@c @code{EOVERFLOW}. 2348@end deftypefun 2349 2350@node Integer Related Functions, Rounding Related Functions, Formatted Output Functions, MPFR Interface 2351@comment node-name, next, previous, up 2352@cindex Integer related functions 2353@section Integer and Remainder Related Functions 2354 2355@deftypefun int mpfr_rint (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 2356@deftypefunx int mpfr_ceil (mpfr_t @var{rop}, mpfr_t @var{op}) 2357@deftypefunx int mpfr_floor (mpfr_t @var{rop}, mpfr_t @var{op}) 2358@deftypefunx int mpfr_round (mpfr_t @var{rop}, mpfr_t @var{op}) 2359@deftypefunx int mpfr_trunc (mpfr_t @var{rop}, mpfr_t @var{op}) 2360Set @var{rop} to @var{op} rounded to an integer. 2361@code{mpfr_rint} rounds to the nearest representable integer in the 2362given direction @var{rnd}, @code{mpfr_ceil} rounds 2363to the next higher or equal representable integer, @code{mpfr_floor} to 2364the next lower or equal representable integer, @code{mpfr_round} to the 2365nearest representable integer, rounding halfway cases away from zero 2366(as in the roundTiesToAway mode of IEEE 754-2008), 2367and @code{mpfr_trunc} to the next representable integer toward zero. 2368 2369The returned value is zero when the result is exact, positive when it is 2370greater than the original value of @var{op}, and negative when it is smaller. 2371More precisely, the returned value is 0 when @var{op} is an integer 2372representable in @var{rop}, 1 or @minus{}1 when @var{op} is an integer 2373that is not representable in @var{rop}, 2 or @minus{}2 when @var{op} is 2374not an integer. 2375 2376Note that @code{mpfr_round} is different from @code{mpfr_rint} called with 2377the rounding to nearest mode (where halfway cases are rounded to an even 2378integer or significand). Note also that no double rounding is performed; for 2379instance, 10.5 (1010.1 in binary) is rounded by @code{mpfr_rint} with 2380rounding to nearest to 12 (1100 2381in binary) in 2-bit precision, because the two enclosing numbers representable 2382on two bits are 8 and 12, and the closest is 12. 2383(If one first rounded to an integer, one would round 10.5 to 10 with 2384even rounding, and then 10 would be rounded to 8 again with even rounding.) 2385@end deftypefun 2386 2387@deftypefun int mpfr_rint_ceil (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 2388@deftypefunx int mpfr_rint_floor (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 2389@deftypefunx int mpfr_rint_round (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 2390@deftypefunx int mpfr_rint_trunc (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 2391Set @var{rop} to @var{op} rounded to an integer. 2392@code{mpfr_rint_ceil} rounds to the next higher or equal integer, 2393@code{mpfr_rint_floor} to the next lower or equal integer, 2394@code{mpfr_rint_round} to the nearest integer, rounding halfway cases away 2395from zero, and @code{mpfr_rint_trunc} to the next integer toward zero. 2396If the result is not representable, it is rounded in the direction @var{rnd}. 2397The returned value is the ternary value associated with the considered 2398round-to-integer function (regarded in the same way as any other 2399mathematical function). 2400Contrary to @code{mpfr_rint}, those functions do perform a double rounding: 2401first @var{op} is rounded to the nearest integer in the direction given by 2402the function name, then this nearest integer (if not representable) is 2403rounded in the given direction @var{rnd}. 2404For example, @code{mpfr_rint_round} with rounding to nearest and a precision 2405of two bits rounds 6.5 to 7 (halfway cases away from zero), then 7 is 2406rounded to 8 by the round-even rule, despite the fact that 6 is also 2407representable on two bits, and is closer to 6.5 than 8. 2408@end deftypefun 2409 2410@deftypefun int mpfr_frac (mpfr_t @var{rop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 2411Set @var{rop} to the fractional part of @var{op}, having the same sign as 2412@var{op}, rounded in the direction @var{rnd} (unlike in @code{mpfr_rint}, 2413@var{rnd} affects only how the exact fractional part is rounded, not how 2414the fractional part is generated). 2415@end deftypefun 2416 2417@deftypefun int mpfr_modf (mpfr_t @var{iop}, mpfr_t @var{fop}, mpfr_t @var{op}, mpfr_rnd_t @var{rnd}) 2418Set simultaneously @var{iop} to the integral part of @var{op} and @var{fop} to 2419the fractional part of @var{op}, rounded in the direction @var{rnd} with the 2420corresponding precision of @var{iop} and @var{fop} (equivalent to 2421@code{mpfr_trunc(@var{iop}, @var{op}, @var{rnd})} and 2422@code{mpfr_frac(@var{fop}, @var{op}, @var{rnd})}). The variables @var{iop} and 2423@var{fop} must be different. Return 0 iff both results are exact (see 2424@code{mpfr_sin_cos} for a more detailed description of the return value). 2425@end deftypefun 2426 2427@deftypefun int mpfr_fmod (mpfr_t @var{r}, mpfr_t @var{x}, mpfr_t @var{y}, mpfr_rnd_t @var{rnd}) 2428@deftypefunx int mpfr_remainder (mpfr_t @var{r}, mpfr_t @var{x}, mpfr_t @var{y}, mpfr_rnd_t @var{rnd}) 2429@deftypefunx int mpfr_remquo (mpfr_t @var{r}, long* @var{q}, mpfr_t @var{x}, mpfr_t @var{y}, mpfr_rnd_t @var{rnd}) 2430Set @var{r} to the value of @math{@var{x} - @var{n}@var{y}}, rounded 2431according to the direction @var{rnd}, where @var{n} is the integer quotient 2432of @var{x} divided by @var{y}, defined as follows: @var{n} is rounded 2433toward zero for @code{mpfr_fmod}, and to the nearest integer (ties rounded 2434to even) for @code{mpfr_remainder} and @code{mpfr_remquo}. 2435 2436Special values are handled as described in Section F.9.7.1 of 2437the ISO C99 standard: 2438If @var{x} is infinite or @var{y} is zero, @var{r} is NaN. 2439If @var{y} is infinite and @var{x} is finite, @var{r} is @var{x} rounded 2440to the precision of @var{r}. 2441If @var{r} is zero, it has the sign of @var{x}. 2442The return value is the ternary value corresponding to @var{r}. 2443 2444Additionally, @code{mpfr_remquo} stores 2445the low significant bits from the quotient @var{n} in @var{*q} 2446(more precisely the number of bits in a @code{long} minus one), 2447with the sign of @var{x} divided by @var{y} 2448(except if those low bits are all zero, in which case zero is returned). 2449Note that @var{x} may be so large in magnitude relative to @var{y} that an 2450exact representation of the quotient is not practical. 2451The @code{mpfr_remainder} and @code{mpfr_remquo} functions are useful for 2452additive argument reduction. 2453@end deftypefun 2454 2455@deftypefun int mpfr_integer_p (mpfr_t @var{op}) 2456Return non-zero iff @var{op} is an integer. 2457@end deftypefun 2458 2459@node Rounding Related Functions, Miscellaneous Functions, Integer Related Functions, MPFR Interface 2460@cindex Rounding mode related functions 2461@section Rounding Related Functions 2462 2463@deftypefun void mpfr_set_default_rounding_mode (mpfr_rnd_t @var{rnd}) 2464Set the default rounding mode to @var{rnd}. 2465The default rounding mode is to nearest initially. 2466@end deftypefun 2467 2468@deftypefun mpfr_rnd_t mpfr_get_default_rounding_mode (void) 2469Get the default rounding mode. 2470@end deftypefun 2471 2472@deftypefun int mpfr_prec_round (mpfr_t @var{x}, mpfr_prec_t @var{prec}, mpfr_rnd_t @var{rnd}) 2473Round @var{x} according to @var{rnd} with precision @var{prec}, which 2474must be an integer between @code{MPFR_PREC_MIN} and @code{MPFR_PREC_MAX} 2475(otherwise the behavior is undefined). 2476If @var{prec} is greater or equal to the precision of @var{x}, then new 2477space is allocated for the significand, and it is filled with zeros. 2478Otherwise, the significand is rounded to precision @var{prec} with the given 2479direction. In both cases, the precision of @var{x} is changed to @var{prec}. 2480 2481Here is an example of how to use @code{mpfr_prec_round} to implement 2482Newton's algorithm to compute the inverse of @var{a}, assuming @var{x} is 2483already an approximation to @var{n} bits: 2484@example 2485 mpfr_set_prec (t, 2 * n); 2486 mpfr_set (t, a, MPFR_RNDN); /* round a to 2n bits */ 2487 mpfr_mul (t, t, x, MPFR_RNDN); /* t is correct to 2n bits */ 2488 mpfr_ui_sub (t, 1, t, MPFR_RNDN); /* high n bits cancel with 1 */ 2489 mpfr_prec_round (t, n, MPFR_RNDN); /* t is correct to n bits */ 2490 mpfr_mul (t, t, x, MPFR_RNDN); /* t is correct to n bits */ 2491 mpfr_prec_round (x, 2 * n, MPFR_RNDN); /* exact */ 2492 mpfr_add (x, x, t, MPFR_RNDN); /* x is correct to 2n bits */ 2493@end example 2494@end deftypefun 2495 2496@deftypefun int mpfr_can_round (mpfr_t @var{b}, mpfr_exp_t @var{err}, mpfr_rnd_t @var{rnd1}, mpfr_rnd_t @var{rnd2}, mpfr_prec_t @var{prec}) 2497Assuming @var{b} is an approximation of an unknown number 2498@var{x} in the direction @var{rnd1} with error at most two to the power 2499E(b)-@var{err} where E(b) is the exponent of @var{b}, return a non-zero 2500value if one is able to round correctly @var{x} to precision 2501@var{prec} with the direction @var{rnd2}, 2502and 0 otherwise (including for NaN and Inf). 2503This function @strong{does not modify} its arguments. 2504 2505If @var{rnd1} is @code{MPFR_RNDN}, then the sign of the error is 2506unknown, but its absolute value is the same, so that the possible range 2507is twice as large as with a directed rounding for @var{rnd1}. 2508 2509Note: if one wants to also determine the correct ternary value when rounding 2510@var{b} to precision @var{prec} with rounding mode @var{rnd}, 2511a useful trick is the following: 2512@verbatim 2513if (mpfr_can_round (b, err, MPFR_RNDN, MPFR_RNDZ, prec + (rnd == MPFR_RNDN))) 2514 ... 2515@end verbatim 2516Indeed, if @var{rnd} is @code{MPFR_RNDN}, this will check if one can 2517round to @var{prec}+1 bits with a directed rounding: 2518if so, one can surely round to nearest to @var{prec} bits, 2519and in addition one can determine the correct ternary value, which would not 2520be the case when @var{b} is near from a value exactly representable on 2521@var{prec} bits. 2522@end deftypefun 2523 2524@deftypefun mpfr_prec_t mpfr_min_prec (mpfr_t @var{x}) 2525Return the minimal number of bits required to store the significand of 2526@var{x}, and 0 for special values, including 0. (Warning: the returned 2527value can be less than @code{MPFR_PREC_MIN}.) 2528 2529The function name is subject to change. 2530@end deftypefun 2531 2532@deftypefun {const char *} mpfr_print_rnd_mode (mpfr_rnd_t @var{rnd}) 2533Return a string ("MPFR_RNDD", "MPFR_RNDU", "MPFR_RNDN", "MPFR_RNDZ", 2534"MPFR_RNDA") corresponding to the rounding mode @var{rnd}, or a null pointer 2535if @var{rnd} is an invalid rounding mode. 2536@end deftypefun 2537 2538@node Miscellaneous Functions, Exception Related Functions, Rounding Related Functions, MPFR Interface 2539@comment node-name, next, previous, up 2540@cindex Miscellaneous float functions 2541@section Miscellaneous Functions 2542 2543@deftypefun void mpfr_nexttoward (mpfr_t @var{x}, mpfr_t @var{y}) 2544If @var{x} or @var{y} is NaN, set @var{x} to NaN. If @var{x} and @var{y} 2545are equal, @var{x} is unchanged. Otherwise, if @var{x} 2546is different from @var{y}, replace @var{x} by the next floating-point 2547number (with the precision of @var{x} and the current exponent range) 2548in the direction of @var{y} 2549(the infinite values are seen as the smallest and largest floating-point 2550numbers). If the result is zero, it keeps the same sign. No underflow or 2551overflow is generated. 2552@end deftypefun 2553 2554@deftypefun void mpfr_nextabove (mpfr_t @var{x}) 2555@deftypefunx void mpfr_nextbelow (mpfr_t @var{x}) 2556Equivalent to @code{mpfr_nexttoward} where @var{y} is plus infinity 2557(resp.@: minus infinity). 2558@end deftypefun 2559 2560@deftypefun int mpfr_min (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 2561@deftypefunx int mpfr_max (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 2562Set @var{rop} to the minimum (resp.@: maximum) 2563of @var{op1} and @var{op2}. If @var{op1} 2564and @var{op2} are both NaN, then @var{rop} is set to NaN. If @var{op1} 2565or @var{op2} is NaN, then @var{rop} is set to the numeric value. If 2566@var{op1} and @var{op2} are zeros of different signs, then @var{rop} 2567is set to @minus{}0 (resp.@: +0). 2568@end deftypefun 2569 2570@deftypefun int mpfr_urandomb (mpfr_t @var{rop}, gmp_randstate_t @var{state}) 2571Generate a uniformly distributed random float in the interval 2572@math{0 @le{} @var{rop} < 1}. More precisely, the number can be seen as a 2573float with a random non-normalized significand and exponent 0, which is then 2574normalized (thus if @var{e} denotes the exponent after normalization, then 2575the least @math{-@var{e}} significant bits of the significand are always 0). 2576 2577Return 0, unless the exponent is not in the current exponent range, in 2578which case @var{rop} is set to NaN and a non-zero value is returned (this 2579should never happen in practice, except in very specific cases). The 2580second argument is a @code{gmp_randstate_t} structure which should be 2581created using the GMP @code{gmp_randinit} function (see the GMP manual). 2582@end deftypefun 2583 2584@deftypefun int mpfr_urandom (mpfr_t @var{rop}, gmp_randstate_t @var{state}, mpfr_rnd_t @var{rnd}) 2585Generate a uniformly distributed random float. 2586The floating-point number @var{rop} can be seen as if a random real number is 2587generated according to the continuous uniform distribution on the interval 2588[0, 1] and then rounded in the direction @var{rnd}. 2589 2590The second argument is a @code{gmp_randstate_t} structure which should be 2591created using the GMP @code{gmp_randinit} function (see the GMP manual). 2592@end deftypefun 2593 2594@deftypefun mpfr_exp_t mpfr_get_exp (mpfr_t @var{x}) 2595Return the exponent of @var{x}, assuming that @var{x} is a non-zero ordinary 2596number and the significand is considered in [1/2,1). The behavior for NaN, 2597infinity or zero is undefined. 2598@end deftypefun 2599 2600@deftypefun int mpfr_set_exp (mpfr_t @var{x}, mpfr_exp_t @var{e}) 2601Set the exponent of @var{x} if @var{e} is in the current exponent range, 2602and return 0 (even if @var{x} is not a non-zero ordinary number); 2603otherwise, return a non-zero value. 2604The significand is assumed to be in [1/2,1). 2605@end deftypefun 2606 2607@deftypefun int mpfr_signbit (mpfr_t @var{op}) 2608Return a non-zero value iff @var{op} has its sign bit set (i.e., if it is 2609negative, @minus{}0, or a NaN whose representation has its sign bit set). 2610@end deftypefun 2611 2612@deftypefun int mpfr_setsign (mpfr_t @var{rop}, mpfr_t @var{op}, int @var{s}, mpfr_rnd_t @var{rnd}) 2613Set the value of @var{rop} from @var{op}, rounded toward the given 2614direction @var{rnd}, then set (resp.@: clear) its sign bit if @var{s} 2615is non-zero (resp.@: zero), even when @var{op} is a NaN. 2616@end deftypefun 2617 2618@deftypefun int mpfr_copysign (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 2619Set the value of @var{rop} from @var{op1}, rounded toward the given 2620direction @var{rnd}, then set its sign bit to that of @var{op2} (even 2621when @var{op1} or @var{op2} is a NaN). This function is equivalent to 2622@code{mpfr_setsign (@var{rop}, @var{op1}, mpfr_signbit (@var{op2}), @var{rnd})}. 2623@end deftypefun 2624 2625@c By definition, a C string is always null-terminated, so that we 2626@c could just say "string" or "null-terminated character array", 2627@c but "null-terminated string" is not an error and probably better 2628@c for most users. 2629@deftypefun {const char *} mpfr_get_version (void) 2630Return the MPFR version, as a null-terminated string. 2631@end deftypefun 2632 2633@defmac MPFR_VERSION 2634@defmacx MPFR_VERSION_MAJOR 2635@defmacx MPFR_VERSION_MINOR 2636@defmacx MPFR_VERSION_PATCHLEVEL 2637@defmacx MPFR_VERSION_STRING 2638@code{MPFR_VERSION} is the version of MPFR as a preprocessing constant. 2639@code{MPFR_VERSION_MAJOR}, @code{MPFR_VERSION_MINOR} and 2640@code{MPFR_VERSION_PATCHLEVEL} are respectively the major, minor and patch 2641level of MPFR version, as preprocessing constants. 2642@code{MPFR_VERSION_STRING} is the version (with an optional suffix, used 2643in development and pre-release versions) as a string constant, which can 2644be compared to the result of @code{mpfr_get_version} to check at run time 2645the header file and library used match: 2646@example 2647if (strcmp (mpfr_get_version (), MPFR_VERSION_STRING)) 2648 fprintf (stderr, "Warning: header and library do not match\n"); 2649@end example 2650Note: Obtaining different strings is not necessarily an error, as 2651in general, a program compiled with some old MPFR version can be 2652dynamically linked with a newer MPFR library version (if allowed 2653by the library versioning system). 2654@end defmac 2655 2656@deftypefn Macro long MPFR_VERSION_NUM (@var{major}, @var{minor}, @var{patchlevel}) 2657Create an integer in the same format as used by @code{MPFR_VERSION} from the 2658given @var{major}, @var{minor} and @var{patchlevel}. 2659Here is an example of how to check the MPFR version at compile time: 2660@example 2661#if (!defined(MPFR_VERSION) || (MPFR_VERSION<MPFR_VERSION_NUM(3,0,0))) 2662# error "Wrong MPFR version." 2663#endif 2664@end example 2665@end deftypefn 2666 2667@deftypefun {const char *} mpfr_get_patches (void) 2668Return a null-terminated string containing the ids of the patches applied to 2669the MPFR library (contents of the @file{PATCHES} file), separated by spaces. 2670Note: If the program has been compiled with an older MPFR version and is 2671dynamically linked with a new MPFR library version, the identifiers of the 2672patches applied to the old (compile-time) MPFR version are not available 2673(however this information should not have much interest in general). 2674@end deftypefun 2675 2676@deftypefun int mpfr_buildopt_tls_p (void) 2677Return a non-zero value if MPFR was compiled as thread safe using 2678compiler-level Thread Local Storage (that is MPFR was built with the 2679@code{--enable-thread-safe} configure option, see @code{INSTALL} file), return 2680zero otherwise. 2681@end deftypefun 2682 2683@deftypefun int mpfr_buildopt_decimal_p (void) 2684Return a non-zero value if MPFR was compiled with decimal float support (that 2685is MPFR was built with the @code{--enable-decimal-float} configure option), 2686return zero otherwise. 2687@end deftypefun 2688 2689@node Exception Related Functions, Compatibility with MPF, Miscellaneous Functions, MPFR Interface 2690@comment node-name, next, previous, up 2691@cindex Exception related functions 2692@section Exception Related Functions 2693 2694@deftypefun mpfr_exp_t mpfr_get_emin (void) 2695@deftypefunx mpfr_exp_t mpfr_get_emax (void) 2696Return the (current) smallest and largest exponents allowed for a 2697floating-point variable. The smallest positive value of a floating-point 2698variable is @m{1/2 \times 2^{\rm emin}, one half times 2 raised to the 2699smallest exponent} and the largest value has the form @m{(1 - \varepsilon) 2700\times 2^{\rm emax}, (1 - epsilon) times 2 raised to the largest exponent}, 2701where @m{\varepsilon,epsilon} depends on the precision of the considered 2702variable. 2703@end deftypefun 2704 2705@deftypefun int mpfr_set_emin (mpfr_exp_t @var{exp}) 2706@deftypefunx int mpfr_set_emax (mpfr_exp_t @var{exp}) 2707Set the smallest and largest exponents allowed for a floating-point variable. 2708Return a non-zero value when @var{exp} is not in the range accepted by the 2709implementation (in that case the smallest or largest exponent is not changed), 2710and zero otherwise. 2711If the user changes the exponent range, it is her/his responsibility to check 2712that all current floating-point variables are in the new allowed range 2713(for example using @code{mpfr_check_range}), otherwise the subsequent 2714behavior will be undefined, in the sense of the ISO C standard. 2715@c It is also her/his responsibility to check that @m {emin <= emax}. 2716@end deftypefun 2717 2718@deftypefun mpfr_exp_t mpfr_get_emin_min (void) 2719@deftypefunx mpfr_exp_t mpfr_get_emin_max (void) 2720@deftypefunx mpfr_exp_t mpfr_get_emax_min (void) 2721@deftypefunx mpfr_exp_t mpfr_get_emax_max (void) 2722Return the minimum and maximum of the exponents 2723allowed for @code{mpfr_set_emin} and @code{mpfr_set_emax} respectively. 2724These values are implementation dependent, thus a program using 2725@code{mpfr_set_emax(mpfr_get_emax_max())} 2726or @code{mpfr_set_emin(mpfr_get_emin_min())} may not be portable. 2727@end deftypefun 2728 2729@deftypefun int mpfr_check_range (mpfr_t @var{x}, int @var{t}, mpfr_rnd_t @var{rnd}) 2730This function assumes that @var{x} is the correctly-rounded value of some 2731real value @var{y} in the direction @var{rnd} and some extended exponent 2732range, and that @var{t} is the corresponding ternary value. 2733For example, one performed @code{t = mpfr_log (x, u, rnd)}, and @var{y} is the 2734exact logarithm of @var{u}. 2735Thus @var{t} is negative if @var{x} is smaller than @var{y}, 2736positive if @var{x} is larger than @var{y}, and zero if @var{x} equals @var{y}. 2737This function modifies @var{x} if needed 2738to be in the current range of acceptable values: It 2739generates an underflow or an overflow if the exponent of @var{x} is 2740outside the current allowed range; the value of @var{t} may be used 2741to avoid a double rounding. This function returns zero if the new value of 2742@var{x} equals the exact one @var{y}, a positive value if that new value 2743is larger than @var{y}, and a negative value if it is smaller than @var{y}. 2744Note that unlike most functions, 2745the new result @var{x} is compared to the (unknown) exact one @var{y}, 2746not the input value @var{x}, i.e., the ternary value is propagated. 2747 2748Note: If @var{x} is an infinity and @var{t} is different from zero (i.e., 2749if the rounded result is an inexact infinity), then the overflow flag is 2750set. This is useful because @code{mpfr_check_range} is typically called 2751(at least in MPFR functions) after restoring the flags that could have 2752been set due to internal computations. 2753@end deftypefun 2754 2755@deftypefun int mpfr_subnormalize (mpfr_t @var{x}, int @var{t}, mpfr_rnd_t @var{rnd}) 2756This function rounds @var{x} emulating subnormal number arithmetic: 2757if @var{x} is outside the subnormal exponent range, it just propagates the 2758ternary value @var{t}; otherwise, it rounds @var{x} to precision 2759@code{EXP(x)-emin+1} according to rounding mode @var{rnd} and previous 2760ternary value @var{t}, avoiding double rounding problems. 2761More precisely in the subnormal domain, denoting by @var{e} the value of 2762@code{emin}, @var{x} is rounded in fixed-point 2763arithmetic to an integer multiple of @m{2^{e-1}, two to the power 2764@var{e}@minus{}1}; as a consequence, @m{1.5 \times 2^{e-1}, 27651.5 multiplied by two to the power @var{e}@minus{}1} when @var{t} is zero 2766is rounded to @m{2^e, two to the power @var{e}} with rounding to nearest. 2767 2768@code{PREC(x)} is not modified by this function. 2769@var{rnd} and @var{t} must be the rounding mode 2770and the returned ternary value used when computing @var{x} 2771(as in @code{mpfr_check_range}). 2772The subnormal exponent range is from @code{emin} to @code{emin+PREC(x)-1}. 2773If the result cannot be represented in the current exponent range 2774(due to a too small @code{emax}), the behavior is undefined. 2775Note that unlike most functions, the result is compared to the exact one, 2776not the input value @var{x}, i.e., the ternary value is propagated. 2777 2778As usual, if the returned ternary value is non zero, the inexact flag is set. 2779Moreover, if a second rounding occurred (because the input @var{x} was in the 2780subnormal range), the underflow flag is set. 2781@end deftypefun 2782 2783This is an example of how to emulate binary double IEEE 754 arithmetic 2784(binary64 in IEEE 754-2008) using MPFR: 2785 2786@example 2787@{ 2788 mpfr_t xa, xb; int i; volatile double a, b; 2789 2790 mpfr_set_default_prec (53); 2791 mpfr_set_emin (-1073); mpfr_set_emax (1024); 2792 2793 mpfr_init (xa); mpfr_init (xb); 2794 2795 b = 34.3; mpfr_set_d (xb, b, MPFR_RNDN); 2796 a = 0x1.1235P-1021; mpfr_set_d (xa, a, MPFR_RNDN); 2797 2798 a /= b; 2799 i = mpfr_div (xa, xa, xb, MPFR_RNDN); 2800 i = mpfr_subnormalize (xa, i, MPFR_RNDN); /* new ternary value */ 2801 2802 mpfr_clear (xa); mpfr_clear (xb); 2803@} 2804@end example 2805 2806Warning: this emulates a double IEEE 754 arithmetic with correct rounding 2807in the subnormal range, which may not be the case for your hardware. 2808 2809@deftypefun void mpfr_clear_underflow (void) 2810@deftypefunx void mpfr_clear_overflow (void) 2811@deftypefunx void mpfr_clear_nanflag (void) 2812@deftypefunx void mpfr_clear_inexflag (void) 2813@deftypefunx void mpfr_clear_erangeflag (void) 2814Clear the underflow, overflow, invalid, inexact and @emph{erange} flags. 2815@end deftypefun 2816 2817@deftypefun void mpfr_set_underflow (void) 2818@deftypefunx void mpfr_set_overflow (void) 2819@deftypefunx void mpfr_set_nanflag (void) 2820@deftypefunx void mpfr_set_inexflag (void) 2821@deftypefunx void mpfr_set_erangeflag (void) 2822Set the underflow, overflow, invalid, inexact and @emph{erange} flags. 2823@end deftypefun 2824 2825@deftypefun void mpfr_clear_flags (void) 2826Clear all global flags (underflow, overflow, invalid, inexact, @emph{erange}). 2827@end deftypefun 2828 2829@deftypefun int mpfr_underflow_p (void) 2830@deftypefunx int mpfr_overflow_p (void) 2831@deftypefunx int mpfr_nanflag_p (void) 2832@deftypefunx int mpfr_inexflag_p (void) 2833@deftypefunx int mpfr_erangeflag_p (void) 2834Return the corresponding (underflow, overflow, invalid, inexact, @emph{erange}) 2835flag, which is non-zero iff the flag is set. 2836@end deftypefun 2837 2838@node Compatibility with MPF, Custom Interface, Exception Related Functions, MPFR Interface 2839@cindex Compatibility with MPF 2840@section Compatibility With MPF 2841 2842A header file @file{mpf2mpfr.h} is included in the distribution of MPFR for 2843compatibility with the GNU MP class MPF. 2844By inserting the following two lines after the @code{#include <gmp.h>} line, 2845@verbatim 2846#include <mpfr.h> 2847#include <mpf2mpfr.h> 2848@end verbatim 2849@noindent 2850any program written for 2851MPF can be compiled directly with MPFR without any changes 2852(except the @code{gmp_printf} functions will not work for arguments of type 2853@code{mpfr_t}). 2854All operations are then performed with the default MPFR rounding mode, 2855which can be reset with @code{mpfr_set_default_rounding_mode}. 2856 2857Warning: the @code{mpf_init} and @code{mpf_init2} functions initialize 2858to zero, whereas the corresponding MPFR functions initialize to NaN: 2859this is useful to detect uninitialized values, but is slightly incompatible 2860with MPF. 2861 2862@deftypefun void mpfr_set_prec_raw (mpfr_t @var{x}, mpfr_prec_t @var{prec}) 2863Reset the precision of @var{x} to be @strong{exactly} @var{prec} bits. 2864The only difference with @code{mpfr_set_prec} is that @var{prec} is assumed to 2865be small enough so that the significand fits into the current allocated memory 2866space for @var{x}. Otherwise the behavior is undefined. 2867@end deftypefun 2868 2869@deftypefun int mpfr_eq (mpfr_t @var{op1}, mpfr_t @var{op2}, unsigned long int @var{op3}) 2870Return non-zero if @var{op1} and @var{op2} are both non-zero ordinary 2871numbers with the same exponent and the same first @var{op3} bits, both 2872zero, or both infinities of the same sign. Return zero otherwise. 2873This function is defined for compatibility with MPF, we do not recommend 2874to use it otherwise. 2875Do not use it either if 2876you want to know whether two numbers are close to each other; for instance, 28771.011111 and 1.100000 are regarded as different for any value of 2878@var{op3} larger than 1. 2879@end deftypefun 2880 2881@deftypefun void mpfr_reldiff (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpfr_rnd_t @var{rnd}) 2882Compute the relative difference between @var{op1} and @var{op2} 2883and store the result in @var{rop}. 2884This function does not guarantee the correct rounding on the relative 2885difference; it just computes @math{|@var{op1}-@var{op2}|/@var{op1}}, using the 2886precision of @var{rop} and the rounding mode @var{rnd} for all operations. 2887@c VL: say that if op1 and op2 have the same precision and are close to 2888@c each other, then one gets correct rounding? 2889@end deftypefun 2890 2891@deftypefun int mpfr_mul_2exp (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mpfr_rnd_t @var{rnd}) 2892@deftypefunx int mpfr_div_2exp (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mpfr_rnd_t @var{rnd}) 2893These functions are identical to @code{mpfr_mul_2ui} and @code{mpfr_div_2ui} 2894respectively. 2895These functions are only kept for compatibility with MPF, one should 2896prefer @code{mpfr_mul_2ui} and @code{mpfr_div_2ui} otherwise. 2897@end deftypefun 2898 2899 2900@node Custom Interface, Internals, Compatibility with MPF, MPFR Interface 2901@cindex Custom interface 2902@section Custom Interface 2903 2904Some applications use a stack to handle the memory and their objects. 2905However, the MPFR memory design is not well suited for such a thing. So that 2906such applications are able to use MPFR, an auxiliary memory interface has 2907been created: the Custom Interface. 2908 2909The following interface allows one to use MPFR in two ways: 2910@itemize 2911@item Either directly store a floating-point number as a @code{mpfr_t} 2912on the stack. 2913@item Either store its own representation on the 2914stack and construct a new temporary @code{mpfr_t} each time it is needed. 2915@end itemize 2916Nothing has to be done to destroy the floating-point 2917numbers except garbaging the used 2918memory: all the memory management (allocating, destroying, garbaging) is left 2919to the application. 2920 2921Each function in this interface is also implemented as a macro for 2922efficiency reasons: for example @code{mpfr_custom_init (s, p)} 2923uses the macro, while @code{(mpfr_custom_init) (s, p)} uses the function. 2924 2925Note 1: MPFR functions may still initialize temporary floating-point numbers 2926using @code{mpfr_init} and similar functions. See Custom Allocation (GNU MP). 2927 2928Note 2: MPFR functions may use the cached functions (@code{mpfr_const_pi} for 2929example), even if they are not explicitly called. You have to call 2930@code{mpfr_free_cache} each time you garbage the memory iff @code{mpfr_init}, 2931through GMP Custom Allocation, allocates its memory on the application stack. 2932 2933@deftypefun size_t mpfr_custom_get_size (mpfr_prec_t @var{prec}) 2934Return the needed size in bytes to store the significand of a floating-point 2935number of precision @var{prec}. 2936@end deftypefun 2937 2938@deftypefun void mpfr_custom_init (void *@var{significand}, mpfr_prec_t @var{prec}) 2939Initialize a significand of precision @var{prec}, where 2940@var{significand} must be an area of @code{mpfr_custom_get_size (prec)} bytes 2941at least and be suitably aligned for an array of @code{mp_limb_t} (GMP type, 2942@pxref{Internals}). 2943@c PZ: give an example how to align? 2944@end deftypefun 2945 2946@deftypefun void mpfr_custom_init_set (mpfr_t @var{x}, int @var{kind}, mpfr_exp_t @var{exp}, mpfr_prec_t @var{prec}, void *@var{significand}) 2947Perform a dummy initialization of a @code{mpfr_t} and set it to: 2948@itemize 2949@item if @code{ABS(kind) == MPFR_NAN_KIND}, @var{x} is set to NaN; 2950@item if @code{ABS(kind) == MPFR_INF_KIND}, @var{x} is set to the infinity 2951of sign @code{sign(kind)}; 2952@item if @code{ABS(kind) == MPFR_ZERO_KIND}, @var{x} is set to the zero of 2953sign @code{sign(kind)}; 2954@item if @code{ABS(kind) == MPFR_REGULAR_KIND}, @var{x} is set to a regular 2955number: @code{x = sign(kind)*significand*2^exp}. 2956@end itemize 2957In all cases, it uses @var{significand} directly for further computing 2958involving @var{x}. It will not allocate anything. 2959A floating-point number initialized with this function cannot be resized using 2960@code{mpfr_set_prec} or @code{mpfr_prec_round}, 2961or cleared using @code{mpfr_clear}! 2962The @var{significand} must have been initialized with @code{mpfr_custom_init} 2963using the same precision @var{prec}. 2964@end deftypefun 2965 2966@deftypefun int mpfr_custom_get_kind (mpfr_t @var{x}) 2967Return the current kind of a @code{mpfr_t} as created by 2968@code{mpfr_custom_init_set}. 2969The behavior of this function for any @code{mpfr_t} not initialized 2970with @code{mpfr_custom_init_set} is undefined. 2971@end deftypefun 2972 2973@deftypefun {void *} mpfr_custom_get_significand (mpfr_t @var{x}) 2974Return a pointer to the significand used by a @code{mpfr_t} initialized with 2975@code{mpfr_custom_init_set}. 2976The behavior of this function for any @code{mpfr_t} not initialized 2977with @code{mpfr_custom_init_set} is undefined. 2978@end deftypefun 2979 2980@deftypefun mpfr_exp_t mpfr_custom_get_exp (mpfr_t @var{x}) 2981Return the exponent of @var{x}, assuming that @var{x} is a non-zero ordinary 2982number. The return value for NaN, Infinity or zero is unspecified but does not 2983produce any trap. 2984The behavior of this function for any @code{mpfr_t} not initialized 2985with @code{mpfr_custom_init_set} is undefined. 2986@end deftypefun 2987 2988@deftypefun void mpfr_custom_move (mpfr_t @var{x}, void *@var{new_position}) 2989Inform MPFR that the significand of @var{x} has moved due to a garbage collect 2990and update its new position to @code{new_position}. 2991However the application has to move the significand and the @code{mpfr_t} 2992itself. 2993The behavior of this function for any @code{mpfr_t} not initialized 2994with @code{mpfr_custom_init_set} is undefined. 2995@end deftypefun 2996 2997@node Internals, , Custom Interface, MPFR Interface 2998@cindex Internals 2999@section Internals 3000 3001@cindex Limb 3002@c @tindex @code{mp_limb_t} 3003@noindent 3004A @dfn{limb} means the part of a multi-precision number that fits in a single 3005word. Usually a limb contains 300632 or 64 bits. The C data type for a limb is @code{mp_limb_t}. 3007 3008The @code{mpfr_t} type is internally defined as a one-element 3009array of a structure, and @code{mpfr_ptr} is the C data type representing 3010a pointer to this structure. 3011The @code{mpfr_t} type consists of four fields: 3012 3013@itemize @bullet 3014 3015@item The @code{_mpfr_prec} field is used to store the precision of 3016the variable (in bits); this is not less than @code{MPFR_PREC_MIN}. 3017 3018@item The @code{_mpfr_sign} field is used to store the sign of the variable. 3019 3020@item The @code{_mpfr_exp} field stores the exponent. 3021An exponent of 0 means a radix point just above the most significant 3022limb. Non-zero values @math{n} are a multiplier @math{2^n} relative to that 3023point. 3024A NaN, an infinity and a zero are indicated by special values of the exponent 3025field. 3026 3027@item Finally, the @code{_mpfr_d} field is a pointer to the limbs, least 3028significant limbs stored first. 3029The number of limbs in use is controlled by @code{_mpfr_prec}, namely 3030ceil(@code{_mpfr_prec}/@code{mp_bits_per_limb}). 3031Non-singular (i.e., different from NaN, Infinity or zero) 3032values always have the most significant bit of the most 3033significant limb set to 1. When the precision does not correspond to a 3034whole number of limbs, the excess bits at the low end of the data are zeros. 3035 3036@end itemize 3037 3038@node API Compatibility, Contributors, MPFR Interface, Top 3039@chapter API Compatibility 3040 3041The goal of this section is to describe some API changes that occurred 3042from one version of MPFR to another, and how to write code that can be compiled 3043and run with older MPFR versions. The minimum MPFR version that is 3044considered here is 2.2.0 (released on 20 September 2005). 3045 3046API changes can only occur between major or minor versions. Thus the 3047patchlevel (the third number in the MPFR version) will be ignored in 3048the following. If a program does not use MPFR internals, changes in 3049the behavior between two versions differing only by the patchlevel 3050should only result from what was regarded as a bug or unspecified behavior. 3051@comment This includes undefined behavior. 3052 3053As a general rule, a program written for some MPFR version should work 3054with later versions, possibly except at a new major version, where 3055some features (described as obsolete for some time) can be removed. 3056In such a case, a failure should occur during compilation or linking. 3057If a result becomes incorrect because of such a change, please look 3058at the various changes below (they are minimal, and most software 3059should be unaffected), at the FAQ and at the MPFR web page for your 3060version (a bug could have been introduced and be already fixed); 3061and if the problem is not mentioned, please send us a bug report 3062(@pxref{Reporting Bugs}). 3063 3064However, a program written for the current MPFR version (as documented 3065by this manual) may not necessarily work with previous versions of 3066MPFR. This section should help developers to write portable code. 3067 3068Note: Information given here may be incomplete. API changes are 3069also described in the NEWS file (for each version, instead of being 3070classified like here), together with other changes. 3071 3072@menu 3073* Type and Macro Changes:: 3074* Added Functions:: 3075* Changed Functions:: 3076* Removed Functions:: 3077* Other Changes:: 3078@end menu 3079 3080@node Type and Macro Changes, Added Functions, API Compatibility, API Compatibility 3081@section Type and Macro Changes 3082 3083@comment r6789 3084The official type for exponent values changed from @code{mp_exp_t} to 3085@code{mpfr_exp_t} in MPFR 3.0. The type @code{mp_exp_t} will remain 3086available as it comes from GMP (with a different meaning). These types 3087are currently the same (@code{mpfr_exp_t} is defined as @code{mp_exp_t} 3088with @code{typedef}), so that programs can still use @code{mp_exp_t}; 3089but this may change in the future. 3090Alternatively, using the following code after including @file{mpfr.h} 3091will work with official MPFR versions, as @code{mpfr_exp_t} was never 3092defined in MPFR 2.x: 3093@example 3094#if MPFR_VERSION_MAJOR < 3 3095typedef mp_exp_t mpfr_exp_t; 3096#endif 3097@end example 3098 3099The official types for precision values and for rounding modes 3100respectively changed from @code{mp_prec_t} and @code{mp_rnd_t} 3101to @code{mpfr_prec_t} and @code{mpfr_rnd_t} in MPFR 3.0. This 3102change was actually done a long time ago in MPFR, at least since 3103MPFR 2.2.0, with the following code in @file{mpfr.h}: 3104@example 3105#ifndef mp_rnd_t 3106# define mp_rnd_t mpfr_rnd_t 3107#endif 3108#ifndef mp_prec_t 3109# define mp_prec_t mpfr_prec_t 3110#endif 3111@end example 3112This means that it is safe to use the new official types 3113@code{mpfr_prec_t} and @code{mpfr_rnd_t} in your programs. 3114The types @code{mp_prec_t} and @code{mp_rnd_t} (defined 3115in MPFR only) may be removed in the future, as the prefix 3116@code{mp_} is reserved by GMP. 3117 3118@comment r6787 3119The precision type @code{mpfr_prec_t} (@code{mp_prec_t}) was unsigned 3120before MPFR 3.0; it is now signed. @code{MPFR_PREC_MAX} has not changed, 3121though. Indeed the MPFR code requires that @code{MPFR_PREC_MAX} be 3122representable in the exponent type, which may have the same size as 3123@code{mpfr_prec_t} but has always been signed. 3124The consequence is that valid code that does not assume anything about 3125the signedness of @code{mpfr_prec_t} should work with past and new MPFR 3126versions. 3127This change was useful as the use of unsigned types tends to convert 3128signed values to unsigned ones in expressions due to the usual arithmetic 3129conversions, which can yield incorrect results if a negative value is 3130converted in such a way. 3131Warning! A program assuming (intentionally or not) that 3132@code{mpfr_prec_t} is signed may be affected by this problem when 3133it is built and run against MPFR 2.x. 3134 3135The rounding modes @code{GMP_RNDx} were renamed to @code{MPFR_RNDx} 3136in MPFR 3.0. However the old names @code{GMP_RNDx} have been kept for 3137compatibility (this might change in future versions), using: 3138@example 3139#define GMP_RNDN MPFR_RNDN 3140#define GMP_RNDZ MPFR_RNDZ 3141#define GMP_RNDU MPFR_RNDU 3142#define GMP_RNDD MPFR_RNDD 3143@end example 3144The rounding mode ``round away from zero'' (@code{MPFR_RNDA}) was added in 3145MPFR 3.0 (however no rounding mode @code{GMP_RNDA} exists). 3146 3147@node Added Functions, Changed Functions, Type and Macro Changes, API Compatibility 3148@section Added Functions 3149 3150We give here in alphabetical order 3151the functions that were added after MPFR 2.2, and in which 3152MPFR version. 3153 3154@comment The functions are listed in such a way that if a developer wonders 3155@comment whether some function existed in some previous version, then he can 3156@comment find this very quickly. 3157 3158@itemize @bullet 3159 3160@item @code{mpfr_add_d} in MPFR 2.4. 3161 3162@item @code{mpfr_ai} in MPFR 3.0 (incomplete, experimental). 3163 3164@item @code{mpfr_asprintf} in MPFR 2.4. 3165 3166@item @code{mpfr_buildopt_decimal_p} and @code{mpfr_buildopt_tls_p} in MPFR 3.0. 3167 3168@item @code{mpfr_copysign} in MPFR 2.3. 3169Note: MPFR 2.2 had a @code{mpfr_copysign} function that was available, 3170but not documented, 3171and with a slight difference in the semantics (when 3172the second input operand is a NaN). 3173 3174@item @code{mpfr_custom_get_significand} in MPFR 3.0. 3175This function was named @code{mpfr_custom_get_mantissa} in previous 3176versions; @code{mpfr_custom_get_mantissa} is still available via a 3177macro in @file{mpfr.h}: 3178@example 3179#define mpfr_custom_get_mantissa mpfr_custom_get_significand 3180@end example 3181Thus code that needs to work with both MPFR 2.x and MPFR 3.x should 3182use @code{mpfr_custom_get_mantissa}. 3183 3184@item @code{mpfr_d_div} and @code{mpfr_d_sub} in MPFR 2.4. 3185 3186@item @code{mpfr_digamma} in MPFR 3.0. 3187 3188@item @code{mpfr_div_d} in MPFR 2.4. 3189 3190@item @code{mpfr_fmod} in MPFR 2.4. 3191 3192@item @code{mpfr_fms} in MPFR 2.3. 3193 3194@item @code{mpfr_fprintf} in MPFR 2.4. 3195 3196@item @code{mpfr_get_flt} in MPFR 3.0. 3197 3198@item @code{mpfr_get_patches} in MPFR 2.3. 3199 3200@item @code{mpfr_get_z_2exp} in MPFR 3.0. 3201This function was named @code{mpfr_get_z_exp} in previous versions; 3202@code{mpfr_get_z_exp} is still available via a macro in @file{mpfr.h}: 3203@example 3204#define mpfr_get_z_exp mpfr_get_z_2exp 3205@end example 3206Thus code that needs to work with both MPFR 2.x and MPFR 3.x should 3207use @code{mpfr_get_z_exp}. 3208 3209@item @code{mpfr_j0}, @code{mpfr_j1} and @code{mpfr_jn} in MPFR 2.3. 3210 3211@item @code{mpfr_lgamma} in MPFR 2.3. 3212 3213@item @code{mpfr_li2} in MPFR 2.4. 3214 3215@item @code{mpfr_modf} in MPFR 2.4. 3216 3217@item @code{mpfr_mul_d} in MPFR 2.4. 3218 3219@item @code{mpfr_printf} in MPFR 2.4. 3220 3221@item @code{mpfr_rec_sqrt} in MPFR 2.4. 3222 3223@item @code{mpfr_regular_p} in MPFR 3.0. 3224 3225@item @code{mpfr_remainder} and @code{mpfr_remquo} in MPFR 2.3. 3226 3227@item @code{mpfr_set_flt} in MPFR 3.0. 3228 3229@item @code{mpfr_set_z_2exp} in MPFR 3.0. 3230 3231@item @code{mpfr_set_zero} in MPFR 3.0. 3232 3233@item @code{mpfr_setsign} in MPFR 2.3. 3234 3235@item @code{mpfr_signbit} in MPFR 2.3. 3236 3237@item @code{mpfr_sinh_cosh} in MPFR 2.4. 3238 3239@item @code{mpfr_snprintf} and @code{mpfr_sprintf} in MPFR 2.4. 3240 3241@item @code{mpfr_sub_d} in MPFR 2.4. 3242 3243@item @code{mpfr_urandom} in MPFR 3.0. 3244 3245@item @code{mpfr_vasprintf}, @code{mpfr_vfprintf}, @code{mpfr_vprintf}, 3246 @code{mpfr_vsprintf} and @code{mpfr_vsnprintf} in MPFR 2.4. 3247 3248@item @code{mpfr_y0}, @code{mpfr_y1} and @code{mpfr_yn} in MPFR 2.3. 3249 3250@end itemize 3251 3252@node Changed Functions, Removed Functions, Added Functions, API Compatibility 3253@section Changed Functions 3254 3255The following functions have changed after MPFR 2.2. Changes can affect 3256the behavior of code written for some MPFR version when built and run 3257against another MPFR version (older or newer), as described below. 3258 3259@itemize @bullet 3260 3261@item @code{mpfr_check_range} changed in MPFR 2.3.2 and MPFR 2.4. 3262If the value is an inexact infinity, the overflow flag is now set 3263(in case it was lost), while it was previously left unchanged. 3264This is really what is expected in practice (and what the MPFR code 3265was expecting), so that the previous behavior was regarded as a bug. 3266Hence the change in MPFR 2.3.2. 3267 3268@item @code{mpfr_get_f} changed in MPFR 3.0. 3269This function was returning zero, except for NaN and Inf, which do not 3270exist in MPF. The @emph{erange} flag is now set in these cases, 3271and @code{mpfr_get_f} now returns the usual ternary value. 3272 3273@item @code{mpfr_get_si}, @code{mpfr_get_sj}, @code{mpfr_get_ui} 3274and @code{mpfr_get_uj} changed in MPFR 3.0. 3275In previous MPFR versions, the cases where the @emph{erange} flag 3276is set were unspecified. 3277 3278@item @code{mpfr_get_z} changed in MPFR 3.0. 3279The return type was @code{void}; it is now @code{int}, and the usual 3280ternary value is returned. Thus programs that need to work with both 3281MPFR 2.x and 3.x must not use the return value. Even in this case, 3282C code using @code{mpfr_get_z} as the second or third term of 3283a conditional operator may also be affected. For instance, the 3284following is correct with MPFR 3.0, but not with MPFR 2.x: 3285@example 3286 bool ? mpfr_get_z(...) : mpfr_add(...); 3287@end example 3288On the other hand, the following is correct with MPFR 2.x, but not 3289with MPFR 3.0: 3290@example 3291 bool ? mpfr_get_z(...) : (void) mpfr_add(...); 3292@end example 3293Portable code should cast @code{mpfr_get_z(...)} to @code{void} to 3294use the type @code{void} for both terms of the conditional operator, 3295as in: 3296@example 3297 bool ? (void) mpfr_get_z(...) : (void) mpfr_add(...); 3298@end example 3299Alternatively, @code{if ... else} can be used instead of the 3300conditional operator. 3301 3302Moreover the cases where the @emph{erange} flag is set were unspecified 3303in MPFR 2.x. 3304 3305@item @code{mpfr_get_z_exp} changed in MPFR 3.0. 3306In previous MPFR versions, the cases where the @emph{erange} flag 3307is set were unspecified. 3308Note: this function has been renamed to @code{mpfr_get_z_2exp} 3309in MPFR 3.0, but @code{mpfr_get_z_exp} is still available for 3310compatibility reasons. 3311 3312@item @code{mpfr_strtofr} changed in MPFR 2.3.1 and MPFR 2.4. 3313This was actually a bug fix since the code and the documentation did 3314not match. But both were changed in order to have a more consistent 3315and useful behavior. The main changes in the code are as follows. 3316The binary exponent is now accepted even without the @code{0b} or 3317@code{0x} prefix. Data corresponding to NaN can now have an optional 3318sign (such data were previously invalid). 3319 3320@item @code{mpfr_strtofr} changed in MPFR 3.0. 3321This function now accepts bases from 37 to 62 (no changes for the other 3322bases). Note: if an unsupported base is provided to this function, 3323the behavior is undefined; more precisely, in MPFR 2.3.1 and later, 3324providing an unsupported base yields an assertion failure (this 3325behavior may change in the future). 3326 3327@item @code{mpfr_subnormalize} changed in MPFR 3.0.1. 3328This was actually regarded as a bug fix. The @code{mpfr_subnormalize} 3329implementation up to MPFR 3.0.0 did not change the flags. In particular, 3330it did not follow the generic rule concerning the inexact flag (and no 3331special behavior was specified). The case of the underflow flag was more 3332a lack of specification. 3333 3334@end itemize 3335 3336@node Removed Functions, Other Changes, Changed Functions, API Compatibility 3337@section Removed Functions 3338 3339Functions @code{mpfr_random} and @code{mpfr_random2} have been 3340removed in MPFR 3.0 (this only affects old code built against 3341MPFR 3.0 or later). 3342(The function @code{mpfr_random} had been deprecated since at least MPFR 2.2.0, 3343and @code{mpfr_random2} since MPFR 2.4.0.) 3344 3345@node Other Changes, , Removed Functions, API Compatibility 3346@section Other Changes 3347 3348@comment r6699 3349For users of a C++ compiler, the way how the availability of @code{intmax_t} 3350is detected has changed in MPFR 3.0. 3351In MPFR 2.x, if a macro @code{INTMAX_C} or @code{UINTMAX_C} was defined 3352(e.g. when the @code{__STDC_CONSTANT_MACROS} macro had been defined 3353before @code{<stdint.h>} or @code{<inttypes.h>} has been included), 3354@code{intmax_t} was assumed to be defined. 3355However this was not always the case (more precisely, @code{intmax_t} 3356can be defined only in the namespace @code{std}, as with Boost), so 3357that compilations could fail. 3358Thus the check for @code{INTMAX_C} or @code{UINTMAX_C} is now disabled for 3359C++ compilers, with the following consequences: 3360 3361@itemize 3362 3363@item Programs written for MPFR 2.x that need @code{intmax_t} may no longer 3364be compiled against MPFR 3.0: a @code{#define MPFR_USE_INTMAX_T} may be 3365necessary before @file{mpfr.h} is included. 3366 3367@item The compilation of programs that work with MPFR 3.0 may fail with 3368MPFR 2.x due to the problem described above. Workarounds are possible, 3369such as defining @code{intmax_t} and @code{uintmax_t} in the global 3370namespace, though this is not clean. 3371 3372@end itemize 3373 3374@node Contributors, References, API Compatibility, Top 3375@comment node-name, next, previous, up 3376@unnumbered Contributors 3377 3378The main developers of MPFR are Guillaume Hanrot, Vincent Lef@`evre, 3379Patrick P@'elissier, Philippe Th@'eveny and Paul Zimmermann. 3380 3381Sylvie Boldo from ENS-Lyon, France, 3382contributed the functions @code{mpfr_agm} and @code{mpfr_log}. 3383Emmanuel Jeandel, from ENS-Lyon too, 3384contributed the generic hypergeometric code, 3385as well as the internal function @code{mpfr_exp3}, 3386a first implementation of the sine and cosine, 3387and improved versions of 3388@code{mpfr_const_log2} and @code{mpfr_const_pi}. 3389Mathieu Dutour contributed the functions @code{mpfr_atan} and @code{mpfr_asin}, 3390and a previous version of @code{mpfr_gamma}; 3391David Daney contributed the hyperbolic and inverse hyperbolic functions, 3392the base-2 exponential, and the factorial function. Fabrice Rouillier 3393contributed the @code{mpfr_xxx_z} and @code{mpfr_xxx_q} functions, 3394and helped to the Microsoft Windows porting. 3395Jean-Luc R@'emy contributed the @code{mpfr_zeta} code. 3396Ludovic Meunier helped in the design of the @code{mpfr_erf} code. 3397Damien Stehl@'e contributed the @code{mpfr_get_ld_2exp} function. 3398Sylvain Chevillard contributed the @code{mpfr_ai} function. 3399 3400We would like to thank Jean-Michel Muller and Joris van der Hoeven for very 3401fruitful discussions at the beginning of that project, Torbj@"orn Granlund 3402and Kevin Ryde for their help about design issues, 3403and Nathalie Revol for her careful reading of a previous version of 3404this documentation. In particular 3405Kevin Ryde did a tremendous job for the portability of MPFR in 2002-2004. 3406 3407The development of the MPFR library would not have been possible without 3408the continuous support of INRIA, and of the LORIA (Nancy, France) and LIP 3409(Lyon, France) laboratories. In particular the main authors were or are 3410members of the PolKA, Spaces, Cacao and Caramel 3411project-teams at LORIA and of the 3412Ar@'enaire project-team at LIP. 3413This project was started during the Fiable (reliable in French) action 3414supported by INRIA, and continued during the AOC action. 3415The development of MPFR was also supported by a grant 3416(202F0659 00 MPN 121) from the Conseil R@'egional de Lorraine in 2002, 3417from INRIA by an "associate engineer" grant (2003-2005), 3418an "op@'eration de d@'eveloppement logiciel" grant (2007-2009), 3419and the post-doctoral grant of Sylvain Chevillard in 2009-2010. 3420 3421@node References, GNU Free Documentation License, Contributors, Top 3422@comment node-name, next, previous, up 3423@unnumbered References 3424 3425@itemize @bullet 3426 3427@item 3428Richard Brent and Paul Zimmermann, 3429"Modern Computer Arithmetic", 3430Cambridge University Press (to appear), 3431also available from the authors' web pages. 3432 3433@item 3434Laurent Fousse, Guillaume Hanrot, Vincent Lef@`evre, 3435Patrick P@'elissier and Paul Zimmermann, 3436"MPFR: A Multiple-Precision Binary Floating-Point Library With Correct Rounding", 3437ACM Transactions on Mathematical Software, 3438volume 33, issue 2, article 13, 15 pages, 2007, 3439@url{http://doi.acm.org/10.1145/1236463.1236468}. 3440 3441@item 3442Torbj@"orn Granlund, "GNU MP: The GNU Multiple Precision Arithmetic Library", 3443 version 5.0.1, 2010, @url{http://gmplib.org}. 3444 3445@item 3446IEEE standard for binary floating-point arithmetic, Technical Report 3447ANSI-IEEE Standard 754-1985, New York, 1985. 3448Approved March 21, 1985: IEEE Standards Board; approved July 26, 3449 1985: American National Standards Institute, 18 pages. 3450 3451@item 3452IEEE Standard for Floating-Point Arithmetic, 3453ANSI-IEEE Standard 754-2008, 2008. 3454Revision of ANSI-IEEE Standard 754-1985, 3455approved June 12, 2008: IEEE Standards Board, 70 pages. 3456 3457@item 3458Donald E. Knuth, "The Art of Computer Programming", vol 2, 3459"Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981. 3460 3461@item 3462Jean-Michel Muller, "Elementary Functions, Algorithms and Implementation", 3463Birkh@"auser, Boston, 2nd edition, 2006. 3464 3465@item 3466Jean-Michel Muller, Nicolas Brisebarre, Florent de Dinechin, 3467Claude-Pierre Jeannerod, Vincent Lef@`evre, Guillaume Melquiond, 3468Nathalie Revol, Damien Stehl@'e and Serge Torr@`es, 3469"Handbook of Floating-Point Arithmetic", 3470Birkh@"auser, Boston, 2009. 3471 3472@end itemize 3473 3474 3475@node GNU Free Documentation License, Concept Index, References, Top 3476@appendix GNU Free Documentation License 3477@cindex GNU Free Documentation License 3478@include fdl.texi 3479 3480 3481@node Concept Index, Function Index, GNU Free Documentation License, Top 3482@comment node-name, next, previous, up 3483@unnumbered Concept Index 3484@printindex cp 3485 3486@node Function Index, , Concept Index, Top 3487@comment node-name, next, previous, up 3488@unnumbered Function and Type Index 3489@printindex fn 3490 3491@bye 3492 3493@c Local variables: 3494@c fill-column: 78 3495@c End: 3496