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