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