Annotation of OpenXM_contrib/gmp/mpfr/mpfr.texi, Revision 1.1
1.1 ! ohara 1: \input texinfo @c -*-texinfo-*-
! 2: @c %**start of header
! 3: @setfilename mpfr.info
! 4: @settitle MPFR 2.0.1
! 5: @synindex tp fn
! 6: @iftex
! 7: @afourpaper
! 8: @end iftex
! 9: @comment %**end of header
! 10:
! 11: @ifinfo
! 12: @format
! 13: START-INFO-DIR-ENTRY
! 14: * mpfr: (mpfr.info). Multiple Precision Floating-Point Reliable Library.
! 15: END-INFO-DIR-ENTRY
! 16: @end format
! 17: @end ifinfo
! 18:
! 19: @c smallbook
! 20:
! 21: @iftex
! 22: @finalout
! 23: @end iftex
! 24:
! 25: @c Note: the edition number is listed in *three* places; please update
! 26: @c all three. Also, update the month and year where appropriate.
! 27:
! 28: @c ==> Update edition number for settitle and subtitle, and in the
! 29: @c ==> following paragraph; update date, too.
! 30:
! 31:
! 32: @ifinfo
! 33: This file documents MPFR, a library for reliable multiple precision floating-point arithmetic
! 34:
! 35: Copyright (C) 1999-2002, Free Software Foundation.
! 36:
! 37: Permission is granted to make and distribute verbatim copies of
! 38: this manual provided the copyright notice and this permission notice
! 39: are preserved on all copies.
! 40:
! 41: @ignore
! 42: Permission is granted to process this file through TeX and print the
! 43: results, provided the printed document carries copying permission
! 44: notice identical to this one except for the removal of this paragraph
! 45: (this paragraph not being relevant to the printed manual).
! 46:
! 47: @end ignore
! 48: Permission is granted to copy and distribute modified versions of this
! 49: manual under the conditions for verbatim copying, provided that the entire
! 50: resulting derived work is distributed under the terms of a permission
! 51: notice identical to this one.
! 52:
! 53: Permission is granted to copy and distribute translations of this manual
! 54: into another language, under the above conditions for modified versions,
! 55: except that this permission notice may be stated in a translation approved
! 56: by the Foundation.
! 57: @end ifinfo
! 58:
! 59: @setchapternewpage on
! 60: @titlepage
! 61: @c use the new format for titles
! 62:
! 63: @title MPFR
! 64: @subtitle The Multiple Precision Floating-Point Reliable Library
! 65: @subtitle Edition 2.0.1
! 66: @subtitle April 2002
! 67:
! 68: @author The MPFR team, LORIA/INRIA Lorraine
! 69:
! 70: @c Include the Distribution inside the titlepage so
! 71: @c that headings are turned off.
! 72:
! 73: @tex
! 74: \global\parindent=0pt
! 75: \global\parskip=8pt
! 76: \global\baselineskip=13pt
! 77: @end tex
! 78:
! 79: @page
! 80: @vskip 0pt plus 1filll
! 81: Copyright @copyright{} 1999-2002 Free Software Foundation
! 82:
! 83: @sp 2
! 84:
! 85: Published by the Free Software Foundation @*
! 86: 59 Temple Place - Suite 330 @*
! 87: Boston, MA 02111-1307, USA @*
! 88:
! 89: Permission is granted to make and distribute verbatim copies of
! 90: this manual provided the copyright notice and this permission notice
! 91: are preserved on all copies.
! 92:
! 93: Permission is granted to copy and distribute modified versions of this
! 94: manual under the conditions for verbatim copying, provided that the entire
! 95: resulting derived work is distributed under the terms of a permission
! 96: notice identical to this one.
! 97:
! 98: Permission is granted to copy and distribute translations of this manual
! 99: into another language, under the above conditions for modified versions,
! 100: except that this permission notice may be stated in a translation approved
! 101: by the Foundation.
! 102: @end titlepage
! 103: @headings double
! 104:
! 105: @ifinfo
! 106: @node Top, Copying, (dir), (dir)
! 107:
! 108: @top MPFR
! 109:
! 110: This manual documents how to install and use the Multiple Precision
! 111: Floating-Point Reliable Library, version 2.0.1
! 112:
! 113: @end ifinfo
! 114:
! 115: @menu
! 116: * Copying:: GMP Copying Conditions (LGPL).
! 117: * Introduction to MPFR:: Brief introduction to MPFR.
! 118: * Installing MPFR:: How to configure and compile the MPFR library.
! 119: * MPFR Basics:: What every MPFR user should now.
! 120: * Reporting Bugs:: How to usefully report bugs.
! 121: * Floating-point Functions:: Functions for arithmetic on floats.
! 122:
! 123: * Contributors::
! 124: * References::
! 125: * Concept Index::
! 126: * Function Index::
! 127: @end menu
! 128:
! 129: @node Copying, Introduction to MPFR, Top, Top
! 130: @comment node-name, next, previous, up
! 131: @unnumbered MPFR Copying Conditions
! 132: @cindex Copying conditions
! 133: @cindex Conditions for copying MPFR
! 134:
! 135: This library is @dfn{free}; this means that everyone is free to use it and
! 136: free to redistribute it on a free basis. The library is not in the public
! 137: domain; it is copyrighted and there are restrictions on its distribution, but
! 138: these restrictions are designed to permit everything that a good cooperating
! 139: citizen would want to do. What is not allowed is to try to prevent others
! 140: from further sharing any version of this library that they might get from
! 141: you.@refill
! 142:
! 143: Specifically, we want to make sure that you have the right to give away copies
! 144: of the library, that you receive source code or else can get it if you want
! 145: it, that you can change this library or use pieces of it in new free programs,
! 146: and that you know you can do these things.@refill
! 147:
! 148: To make sure that everyone has such rights, we have to forbid you to deprive
! 149: anyone else of these rights. For example, if you distribute copies of the
! 150: MPFR library, you must give the recipients all the rights that you have. You
! 151: must make sure that they, too, receive or can get the source code. And you
! 152: must tell them their rights.@refill
! 153:
! 154: Also, for our own protection, we must make certain that everyone finds out
! 155: that there is no warranty for the MPFR library. If it is modified by
! 156: someone else and passed on, we want their recipients to know that what they
! 157: have is not what we distributed, so that any problems introduced by others
! 158: will not reflect on our reputation.@refill
! 159:
! 160: The precise conditions of the license for the MPFR library are found in the
! 161: Lesser General Public License that accompanies the source code.
! 162: See the file COPYING.LIB.@refill
! 163:
! 164: @node Introduction to MPFR, Installing MPFR, Copying, Top
! 165: @comment node-name, next, previous, up
! 166: @chapter Introduction to MPFR
! 167:
! 168:
! 169: MPFR is a portable library written in C for arbitrary precision arithmetic
! 170: on reliable floating-point numbers. It is based on the GNU MP library.
! 171: It aims to extend the class of floating-point numbers provided by the
! 172: GNU MP library by @dfn{reliable} floating-point numbers. It may replace
! 173: the GNU MP floating-point numbers in a future release. The main differences
! 174: with the @code{mpf} class are:
! 175:
! 176: @itemize @bullet
! 177: @item the @code{mpfr} code is portable, i.e. the result of any operation
! 178: does not depend (or should not) on the machine word size
! 179: @code{mp_bits_per_limb} (32 or 64 on most machines);
! 180: @item the precision in bits can be set exactly to any valid value
! 181: for each variable (including very small precision);
! 182: @item @code{mpfr} provides the four rounding modes from the IEEE 754
! 183: standard.
! 184: @end itemize
! 185:
! 186: In particular, with a precision of 53 bits, @code{mpfr} should be able
! 187: to exactly reproduce all computations with double-precision machine
! 188: floating-point
! 189: numbers (@code{double} type in C), except the default exponent range
! 190: is much wider and subnormal numbers are not implemented.
! 191:
! 192: This version of MPFR is released under the GNU Lesser General Public
! 193: License.
! 194: It is permitted to link MPFR to non-free programs, as long as when
! 195: distributing them the MPFR source code and a means to re-link with a
! 196: modified MPFR is provided.
! 197:
! 198: @section How to use this Manual
! 199:
! 200: Everyone should read @ref{MPFR Basics}. If you need to install the library
! 201: yourself, you need to read @ref{Installing MPFR}, too.
! 202:
! 203: The rest of the manual can be used for later reference, although it is
! 204: probably a good idea to glance through it.
! 205:
! 206: @node Installing MPFR, Reporting Bugs, Introduction to MPFR, Top
! 207: @comment node-name, next, previous, up
! 208: @chapter Installing MPFR
! 209: @cindex Installation
! 210:
! 211: To build MPFR, you first have to install GNU MP
! 212: (version 4.0.1 or higher) on your computer.
! 213: You need a C compiler, preferably GCC, but any reasonable compiler should
! 214: work. And you need a standard Unix @samp{make} program, plus some other
! 215: standard Unix utility programs.
! 216:
! 217: Here are the steps needed to install the library on Unix systems
! 218: (more details are provided in the @file{INSTALL} file):
! 219:
! 220: @enumerate
! 221: @item
! 222: In most cases, @samp{./configure --with-gmp=/usr/local/gmp} should work,
! 223: where the directory @samp{/usr/local/gmp} is where you have installed
! 224: GNU MP.
! 225: When you install GNU MP, you have to copy the files
! 226: @samp{config.h},
! 227: @samp{gmp-impl.h}, @samp{gmp-mparam.h} and
! 228: @samp{longlong.h} from the GNU MP source directory
! 229: to @samp{/usr/local/gmp/include};
! 230: these additional files are needed by MPFR.
! 231: If you get error messages, you might check that you use the same compiler
! 232: and compile options as for GNU MP (see the @file{INSTALL} file).
! 233:
! 234: @item
! 235: @samp{make}
! 236:
! 237: This will compile MPFR, and create a library archive file @file{libmpfr.a}
! 238: in the working directory.
! 239:
! 240: @item
! 241: @samp{make check}
! 242:
! 243: This will make sure MPFR was built correctly.
! 244: If you get error messages, please
! 245: report this to @samp{mpfr@@loria.fr}. (@xref{Reporting Bugs}, for
! 246: information on what to include in useful bug reports.)
! 247:
! 248: @item
! 249: @samp{make install}
! 250:
! 251: This will copy the files @file{mpfr.h} and @file{mpf2mpfr.h},
! 252: and @file{libmpfr.a},
! 253: to the directories @file{/usr/local/include} and @file{/usr/local/lib}
! 254: respectively (or if you passed the @samp{--prefix} option to
! 255: @file{configure}, to the directory given as argument to @samp{--prefix}).
! 256: This will also install @file{mpfr.info} in @file{/usr/local/info}.
! 257: @end enumerate
! 258:
! 259: There are some other useful make targets:
! 260:
! 261: @itemize @bullet
! 262: @item
! 263: @samp{mpfr.dvi} or @samp{dvi}
! 264:
! 265: Create a DVI version of the manual, in @file{mpfr.dvi}.
! 266: @c and a set of info files, in @file{mpfr.info}, @file{mpfr.info-1}, @file{mpfr.info-2}, etc.
! 267:
! 268: @item
! 269: @samp{mpfr.ps}
! 270:
! 271: Create a Postscript version of the manual, in @file{mpfr.ps}.
! 272:
! 273: @c @item
! 274: @c @samp{html}
! 275: @c Create a HTML version of the manual, in @file{mpfr.html}.
! 276:
! 277: @item
! 278: @samp{clean}
! 279:
! 280: Delete all object files and archive files, but not the configuration files.
! 281:
! 282: @item
! 283: @samp{distclean}
! 284:
! 285: Delete all files not included in the distribution.
! 286:
! 287: @item
! 288: @samp{uninstall}
! 289: Delete all files copied by @samp{make install}.
! 290: @end itemize
! 291:
! 292:
! 293: @section Known Build Problems
! 294:
! 295: MPFR suffers from all bugs from the GNU MP library, plus many many more.
! 296:
! 297: Please report other problems to @samp{mpfr@@loria.fr}.
! 298: @xref{Reporting Bugs}.
! 299: Some bug fixes are available on the MPFR web page
! 300: @samp{http://www.loria.fr/projets/mpfr/} or @samp{http://www.mpfr.org/}.
! 301:
! 302:
! 303: @node Reporting Bugs, MPFR Basics, Installing MPFR, Top
! 304: @comment node-name, next, previous, up
! 305: @chapter Reporting Bugs
! 306: @cindex Reporting bugs
! 307:
! 308: If you think you have found a bug in the MPFR library, first have a look on the
! 309: MPFR web page @samp{http://www.loria.fr/projets/mpfr/} or
! 310: @samp{http://www.mpfr.org/}: perhaps this bug is already known,
! 311: in which case you will find a workaround for it.
! 312: Otherwise, please investigate
! 313: and report it. We have made this library available to you, and it is not to ask
! 314: too much from you, to ask you to report the bugs that you find.
! 315:
! 316: There are a few things you should think about when you put your bug report
! 317: together.
! 318:
! 319: You have to send us a test case that makes it possible for us to reproduce the
! 320: bug. Include instructions on how to run the test case.
! 321:
! 322: You also have to explain what is wrong; if you get a crash, or if the results
! 323: printed are incorrect and in that case, in what way.
! 324:
! 325: Please include compiler version information
! 326: in your bug report. This can be extracted using @samp{cc -V} on some
! 327: machines, or,
! 328: if you're using gcc, @samp{gcc -v}. Also, include the output from @samp{uname
! 329: -a}.
! 330:
! 331: If your bug report is good, we will do our best to help you to get a corrected
! 332: version of the library; if the bug report is poor, we won't do anything about
! 333: it (aside of chiding you to send better bug reports).
! 334:
! 335: Send your bug report to: @samp{mpfr@@loria.fr}.
! 336:
! 337: If you think something in this manual is unclear, or downright incorrect, or if
! 338: the language needs to be improved, please send a note to the same address.
! 339:
! 340: @node MPFR Basics, Floating-point Functions, Reporting Bugs, Top
! 341: @comment node-name, next, previous, up
! 342: @chapter MPFR Basics
! 343:
! 344:
! 345: @cindex @file{mpfr.h}
! 346: All declarations needed to use MPFR are collected in the include file
! 347: @file{mpfr.h}. It is designed to work with both C and C++ compilers.
! 348: You should include that file in any program using the MPFR library:
! 349:
! 350: @code{#include "mpfr.h"}
! 351:
! 352: @section Nomenclature and Types
! 353:
! 354: @cindex Floating-point number
! 355: @tindex @code{mpfr_t}
! 356: @noindent
! 357: @dfn{Floating-point number} or @dfn{Float} for short, is an arbitrary precision
! 358: mantissa with a limited precision exponent. The C data type for such objects
! 359: is @code{mpfr_t}.
! 360: A floating-point number can have three special values: Not-a-Number (NaN)
! 361: or plus or minus Infinity. NaN represents a value which cannot be represented
! 362: in the floating-point format, like 0 divided by 0, or Infinity minus Infinity.
! 363:
! 364:
! 365: @cindex Precision
! 366: @tindex @code{mp_prec_t}
! 367: @noindent
! 368: The @dfn{Precision} is the number of bits used to represent the mantissa
! 369: of a floating-point number;
! 370: the corresponding C data type is @code{mp_prec_t}.
! 371: The precision can be any integer between @code{MPFR_PREC_MIN} and
! 372: @code{MPFR_PREC_MAX}. In the current implementation, @code{MPFR_PREC_MIN}
! 373: is equal to 2 and @code{MPFR_PREC_MAX} is equal to @code{ULONG_MAX}.
! 374:
! 375: @cindex Rounding Mode
! 376: @tindex @code{mp_rnd_t}
! 377: @noindent
! 378: The @dfn{rounding mode} specifies the way to round the result of a
! 379: floating-point operation, in case the exact result can not be represented
! 380: exactly in the destination mantissa;
! 381: the corresponding C data type is @code{mp_rnd_t}.
! 382:
! 383: @cindex Limb
! 384: @c @tindex @code{mp_limb_t}
! 385: @noindent
! 386: A @dfn{limb} means the part of a multi-precision number that fits in a single
! 387: word. (We chose this word because a limb of the human body is analogous to a
! 388: digit, only larger, and containing several digits.) Normally a limb contains
! 389: 32 or 64 bits. The C data type for a limb is @code{mp_limb_t}.
! 390:
! 391: @section Function Classes
! 392:
! 393: There is only one class of functions in the MPFR library:
! 394:
! 395: @enumerate
! 396: @item
! 397: Functions for floating-point arithmetic, with names beginning with
! 398: @code{mpfr_}. The associated type is @code{mpfr_t}.
! 399: @end enumerate
! 400:
! 401:
! 402: @section MPFR Variable Conventions
! 403:
! 404: As a general rule, all MPFR functions expect output arguments before input
! 405: arguments. This notation is based on an analogy with the assignment operator.
! 406:
! 407: MPFR allows you to use the same variable for both input and output in the same
! 408: expression. For example, the main function for floating-point multiplication,
! 409: @code{mpfr_mul}, can be used like this: @code{mpfr_mul (x, x, x, rnd_mode)}.
! 410: This
! 411: computes the square of @var{x} with rounding mode @code{rnd_mode}
! 412: and puts the result back in @var{x}.
! 413:
! 414: Before you can assign to an MPFR variable, you need to initialize it by calling
! 415: one of the special initialization functions. When you're done with a
! 416: variable, you need to clear it out, using one of the functions for that
! 417: purpose.
! 418:
! 419: A variable should only be initialized once, or at least cleared out between
! 420: each initialization. After a variable has been initialized, it may be
! 421: assigned to any number of times.
! 422:
! 423: For efficiency reasons, avoid to initialize and clear out a variable in loops.
! 424: Instead, initialize it before entering the loop, and clear it out after the
! 425: loop has exited.
! 426:
! 427: You don't need to be concerned about allocating additional space for MPFR
! 428: variables, since any variable has a mantissa of fixed size.
! 429: Hence unless you change its precision, or clear and reinitialize it,
! 430: a floating-point variable will have the same allocated space during all its
! 431: life.
! 432:
! 433: @section Compatibility with MPF
! 434:
! 435: A header file @file{mpf2mpfr.h} is included in the distribution of MPFR for
! 436: compatibility with the GNU MP class MPF.
! 437: After inserting the following two lines after the @code{#include "gmp.h"}
! 438: line,
! 439:
! 440: @code{#include "mpfr.h"}
! 441:
! 442: @code{#include "mpf2mpfr.h"}
! 443:
! 444: any program written for
! 445: MPF can be linked directly with MPFR without any changes.
! 446: All operations are then performed with the default MPFR rounding mode,
! 447: which can be reset with @code{mpfr_set_default_rounding_mode}.
! 448:
! 449: @deftypevr {Global Variable} {mp_rnd_t} __gmp_default_rounding_mode
! 450: The default rounding mode (to nearest initially).
! 451: @end deftypevr
! 452:
! 453: @section Getting the Latest Version of MPFR
! 454:
! 455: The latest version of MPFR is available from
! 456: @samp{http://www.loria.fr/projets/mpfr/} or @samp{http://www.mpfr.org/}.
! 457:
! 458: @node Floating-point Functions, Contributors, MPFR Basics, Top
! 459: @comment node-name, next, previous, up
! 460: @chapter Floating-point Functions
! 461: @cindex Floating-point functions
! 462: @cindex Float functions
! 463:
! 464: The floating-point functions expect arguments of type @code{mpfr_t}.
! 465:
! 466: The MPFR floating-point functions have an interface that is similar to the
! 467: GNU MP
! 468: integer functions. The function prefix for floating-point operations is
! 469: @code{mpfr_}.
! 470:
! 471: There is one significant characteristic of floating-point numbers that has
! 472: motivated a difference between this function class and other MPFR function
! 473: classes: the inherent inexactness of floating-point arithmetic. The user has
! 474: to specify the precision of each variable. A computation that assigns a
! 475: variable will take place with the precision of the assigned variable; the
! 476: cost of that computation should not depend from the
! 477: precision of variables used as input on average.
! 478:
! 479: @cindex User-defined precision
! 480: The precision of a calculation is defined as follows: Compute the requested
! 481: operation exactly (with ``infinite precision''), and round the result to
! 482: the destination variable precision with the given rounding mode.
! 483: Even if the user has asked for a very
! 484: high precision, MP will not calculate with superfluous digits. For example,
! 485: if two low-precision numbers of nearly equal magnitude are added, the
! 486: precision of the result will be limited to what is required to represent the
! 487: result accurately.
! 488:
! 489: The MPFR floating-point functions are intended to be a smooth extension
! 490: of the IEEE P754 arithmetic. The results obtained on one
! 491: computer should not differ from the results obtained on a computer with a
! 492: different word size.
! 493:
! 494: @menu
! 495: * Rounding Modes::
! 496: * Exceptions::
! 497: * Initializing Floats::
! 498: * Assigning Floats::
! 499: * Simultaneous Float Init & Assign::
! 500: * Converting Floats::
! 501: * Float Arithmetic::
! 502: * Float Comparison::
! 503: * I/O of Floats::
! 504: * Miscellaneous Float Functions::
! 505: @end menu
! 506:
! 507: @node Rounding Modes, Exceptions, Floating-point Functions, Floating-point Functions
! 508: @cindex Rounding modes
! 509: @section Rounding Modes
! 510:
! 511: The following four rounding modes are supported:
! 512: @itemize @bullet
! 513: @item @code{GMP_RNDN}: round to nearest
! 514: @item @code{GMP_RNDZ}: round towards zero
! 515: @item @code{GMP_RNDU}: round towards plus infinity
! 516: @item @code{GMP_RNDD}: round towards minus infinity
! 517: @end itemize
! 518: The @samp{round to nearest} mode works as in the IEEE P754 standard: in case
! 519: the number to be rounded lies exactly in the middle of two representable
! 520: numbers, it is rounded to the one with the least significant bit set to zero.
! 521: For example, the number 5, which is represented by (101) in binary, is rounded
! 522: to (100)=4 with a precision of two bits, and not to (110)=6.
! 523: This rule avoids the @dfn{drift} phenomenon mentioned by Knuth in volume 2
! 524: of The Art of Computer Programming (section 4.2.2, pages 221-222).
! 525:
! 526: Most MPFR functions take as first argument the destination variable,
! 527: as second and following arguments the input variables,
! 528: as last argument a rounding mode, and
! 529: have a return value of type @code{int}. If this value is zero, it means
! 530: that the value stored in the destination variable is the exact result of
! 531: the corresponding mathematical function. If the returned value is positive
! 532: (resp. negative), it means the value stored in the destination variable
! 533: is greater (resp. lower) than the exact result.
! 534: For example with the @code{GMP_RNDU} rounding mode, the returned value
! 535: is usually positive, except when the result is exact, in which case it is
! 536: zero.
! 537: In the case of an infinite result, it is considered as inexact when it was
! 538: obtained by overflow, and exact otherwise.
! 539: A NaN result (Not-a-Number) always corresponds to an inexact return value.
! 540:
! 541: @deftypefun void mpfr_set_default_rounding_mode (mp_rnd_t @var{rnd})
! 542: Sets the default rounding mode to @var{rnd}.
! 543: The default rounding mode is to nearest initially.
! 544: @end deftypefun
! 545:
! 546: @deftypefun int mpfr_round_prec (mpfr_t @var{x}, mp_rnd_t @var{rnd}, mp_prec_t @var{prec})
! 547: Rounds @var{x} according to @var{rnd} with precision @var{prec}, which
! 548: may be different from that of @var{x}.
! 549: If @var{prec} is greater or equal to the precision of @var{x}, then new
! 550: space is allocated for the mantissa, and it is filled with zeroes.
! 551: Otherwise, the mantissa is rounded to precision @var{prec} with the given
! 552: direction. In both cases, the precision of @var{x} is changed to @var{prec}.
! 553: The returned value is zero when the result is exact, positive when it is
! 554: greater than the original value of @var{x}, and negative when it is smaller.
! 555: The precision @var{prec} can be any integer between @code{MPFR_PREC_MIN} and
! 556: @code{MPFR_PREC_MAX}.
! 557: @end deftypefun
! 558:
! 559: @deftypefun void mpfr_set_machine_rnd_mode (mp_rnd_t @var{rnd})
! 560: Set the machine rounding mode to @var{rnd}.
! 561: This function is provided only when the operating system supports the
! 562: ISOC9X standard interface for setting rounding modes (i.e. through the
! 563: header file <fenv.h>).
! 564: @end deftypefun
! 565:
! 566: @deftypefun {char *} mpfr_print_rnd_mode (mp_rnd_t @var{rnd})
! 567: Returns the input string (GMP_RNDD, GMP_RNDU, GMP_RNDN, GMP_RNDZ)
! 568: corresponding to the rounding mode @var{rnd} or a null pointer if
! 569: @var{rnd} is an invalid rounding mode.
! 570: @end deftypefun
! 571:
! 572: @node Exceptions, Initializing Floats, Rounding Modes, Floating-point Functions
! 573: @comment node-name, next, previous, up
! 574: @section Exceptions
! 575:
! 576: Note: Overflow handling is still experimental and currently implemented
! 577: very partially. If an overflow occurs internally at the wrong place,
! 578: anything can happen (crash, wrong results, etc).
! 579:
! 580: @deftypefun mp_exp_t mpfr_get_emin (void)
! 581: @deftypefunx mp_exp_t mpfr_get_emax (void)
! 582: Return the (current) smallest and largest exponents allowed for a
! 583: floating-point variable.
! 584: @end deftypefun
! 585:
! 586: @deftypefun int mpfr_set_emin (mp_exp_t @var{exp})
! 587: @deftypefunx int mpfr_set_emax (mp_exp_t @var{exp})
! 588: Set the smallest and largest exponents allowed for a floating-point variable.
! 589: Return a non-zero value when @var{exp} is not in the range accepted by the
! 590: implementation (in that case the smallest or largest exponent is not changed),
! 591: and zero otherwise.
! 592: If the user changes the exponent range, it is her/his responsibility to check
! 593: that all current floating-point variables are in the new allowed range
! 594: (for example using @code{mpfr_check_range},
! 595: otherwise the subsequent
! 596: behaviour will be undefined, in the sense of the ISO C standard.
! 597: @end deftypefun
! 598:
! 599: @deftypefun int mpfr_check_range (mpfr_t @var{x}, mp_rnd_t @var{rnd})
! 600: Return zero if the exponent of @var{x} is in the current allowed range
! 601: (see @code{mpfr_get_emin} and @code{mpfr_get_emax}),
! 602: otherwise reset @var{x} according to the current floating-point system
! 603: and the rounding mode @var{rnd}, and return a positive value if the
! 604: rounded result is larger than the original one, a negative value otherwise
! 605: (the result cannot be exact in that case).
! 606: @end deftypefun
! 607:
! 608: @deftypefun void mpfr_clear_underflow (void)
! 609: @deftypefunx void mpfr_clear_overflow (void)
! 610: @deftypefunx void mpfr_clear_nanflag (void)
! 611: @deftypefunx void mpfr_clear_inexflag (void)
! 612: Clear the underflow, overflow, invalid, and inexact flags.
! 613: @end deftypefun
! 614:
! 615: @deftypefun void mpfr_clear_flags (void)
! 616: Clear all global flags (underflow, overflow, inexact, invalid).
! 617: @end deftypefun
! 618:
! 619: @deftypefun int mpfr_underflow_p (void)
! 620: @deftypefunx int mpfr_overflow_p (void)
! 621: @deftypefunx int mpfr_nanflag_p (void)
! 622: @deftypefunx int mpfr_inexflag_p (void)
! 623: Return the corresponding (underflow, overflow, invalid, inexact) flag,
! 624: which is non-zero iff the flag is set.
! 625: @end deftypefun
! 626:
! 627: @node Initializing Floats, Assigning Floats, Exceptions, Floating-point Functions
! 628: @comment node-name, next, previous, up
! 629: @section Initialization and Assignment Functions
! 630:
! 631: @deftypefun void mpfr_set_default_prec (mp_prec_t @var{prec})
! 632: Set the default precision to be @strong{exactly} @var{prec} bits. The
! 633: precision of a variable means the number of bits used to store its mantissa.
! 634: All
! 635: subsequent calls to @code{mpfr_init} will use this precision, but previously
! 636: initialized variables are unaffected.
! 637: This default precision is set to 53 bits initially.
! 638: The precision can be any integer between @code{MPFR_PREC_MIN} and
! 639: @code{MPFR_PREC_MAX}.
! 640: @end deftypefun
! 641:
! 642: @deftypefun mp_prec_t mpfr_get_default_prec ()
! 643: Returns the default MPFR precision in bits.
! 644: @end deftypefun
! 645:
! 646: An @code{mpfr_t} object must be initialized before storing the first value in
! 647: it. The functions @code{mpfr_init} and @code{mpfr_init2} are used for that
! 648: purpose.
! 649:
! 650: @deftypefun void mpfr_init (mpfr_t @var{x})
! 651: Initialize @var{x}, and set its value to NaN.
! 652: Normally, a variable should be initialized once only
! 653: or at least be cleared, using @code{mpfr_clear}, between initializations. The
! 654: precision of @var{x} is the default precision, which can be changed
! 655: by a call to @code{mpfr_set_default_prec}.
! 656: @end deftypefun
! 657:
! 658: @deftypefun void mpfr_init2 (mpfr_t @var{x}, mp_prec_t @var{prec})
! 659: Initialize @var{x}, set its precision to be @strong{exactly}
! 660: @var{prec} bits, and set its value to NaN.
! 661: Normally, a variable should be initialized once only or at
! 662: least be cleared, using @code{mpfr_clear}, between initializations.
! 663: To change the precision of a variable which has already been initialized,
! 664: use @code{mpfr_set_prec} instead.
! 665: The precision @var{prec} can be any integer between @code{MPFR_PREC_MIN} and
! 666: @code{MPFR_PREC_MAX}.
! 667: @end deftypefun
! 668:
! 669: @deftypefun void mpfr_clear (mpfr_t @var{x})
! 670: Free the space occupied by @var{x}. Make sure to call this function for all
! 671: @code{mpfr_t} variables when you are done with them.
! 672: @end deftypefun
! 673:
! 674: @need 2000
! 675: Here is an example on how to initialize floating-point variables:
! 676: @example
! 677: @{
! 678: mpfr_t x, y;
! 679: mpfr_init (x); /* use default precision */
! 680: mpfr_init2 (y, 256); /* precision @emph{exactly} 256 bits */
! 681: @dots{}
! 682: /* Unless the program is about to exit, do ... */
! 683: mpfr_clear (x);
! 684: mpfr_clear (y);
! 685: @}
! 686: @end example
! 687:
! 688: The following two functions are useful for changing the precision during a
! 689: calculation. A typical use would be for adjusting the precision gradually in
! 690: iterative algorithms like Newton-Raphson, making the computation precision
! 691: closely match the actual accurate part of the numbers.
! 692:
! 693: @deftypefun int mpfr_set_prec (mpfr_t @var{x}, mp_prec_t @var{prec})
! 694: Reset the precision of @var{x} to be @strong{exactly} @var{prec} bits.
! 695: The previous value stored in @var{x} is lost. It is equivalent to
! 696: a call to @code{mpfr_clear(x)} followed by a call to
! 697: @code{mpfr_init2(x, prec)}, but more efficient as no allocation is done in
! 698: case the current allocated space for the mantissa of @var{x} is enough.
! 699: The precision @var{prec} can be any integer between @code{MPFR_PREC_MIN} and
! 700: @code{MPFR_PREC_MAX}.
! 701: It returns a non-zero value iff the memory allocation failed.
! 702:
! 703: In case you want to keep the previous value stored in @var{x},
! 704: use @code{mpfr_round_prec} instead.
! 705: @end deftypefun
! 706:
! 707: @deftypefun mp_prec_t mpfr_get_prec (mpfr_t @var{x})
! 708: Return the precision actually used for assignments of @var{x}, i.e.
! 709: the number of bits used to store its mantissa.
! 710: @end deftypefun
! 711:
! 712: @deftypefun void mpfr_set_prec_raw (mpfr_t @var{x}, unsigned long int @var{p})
! 713: Reset the precision of @var{x} to be @strong{exactly} @var{prec} bits.
! 714: The only difference with @code{mpfr_set_prec} is that @var{p} is assumed to
! 715: be small enough so that the mantissa fits into the current allocated memory
! 716: space for @var{x}. Otherwise an error will occur.
! 717: @end deftypefun
! 718:
! 719: @node Assigning Floats, Simultaneous Float Init & Assign, Initializing Floats, Floating-point Functions
! 720: @comment node-name, next, previous, up
! 721: @section Assignment Functions
! 722: @cindex Float assignment functions
! 723:
! 724: These functions assign new values to already initialized floats
! 725: (@pxref{Initializing Floats}).
! 726:
! 727: @deftypefun int mpfr_set (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 728: @deftypefunx int mpfr_set_ui (mpfr_t @var{rop}, unsigned long int @var{op}, mp_rnd_t @var{rnd})
! 729: @deftypefunx int mpfr_set_si (mpfr_t @var{rop}, long int @var{op}, mp_rnd_t @var{rnd}
! 730: @deftypefunx int mpfr_set_d (mpfr_t @var{rop}, double @var{op}, mp_rnd_t @var{rnd})
! 731: @deftypefunx int mpfr_set_z (mpfr_t @var{rop}, mpz_t @var{op}, mp_rnd_t @var{rnd})
! 732: @deftypefunx int mpfr_set_q (mpfr_t @var{rop}, mpq_t @var{op}, mp_rnd_t @var{rnd})
! 733: Set the value of @var{rop} from @var{op}, rounded to the precision of @var{rop}
! 734: towards the given direction @var{rnd}.
! 735: Please note that even a @code{long int} may have to be rounded,
! 736: if the destination precision is less than the machine word width.
! 737: The return value is zero when @var{rop}=@var{op}, positive when
! 738: @var{rop}>@var{op},
! 739: and negative when @var{rop}<@var{op}.
! 740: For @code{mpfr_set_d}, be careful that the input number @var{op}
! 741: may not be exactly representable as a double-precision number (this happens for
! 742: 0.1 for instance), in which case it is first
! 743: rounded by the C compiler to a double-precision number, and then only
! 744: to a mpfr floating-point number.
! 745: @end deftypefun
! 746:
! 747: @deftypefun int mpfr_set_str (mpfr_t @var{x}, char *@var{s}, int @var{base}, mp_rnd_t @var{rnd})
! 748: Set @var{x} to the value of the string @var{s} in base @var{base} (between
! 749: 2 and 36), rounded in direction @var{rnd} to the precision of @var{x}.
! 750: The exponent is read in decimal.
! 751: This function returns @minus{}1 if an internal overflow occurred (for
! 752: instance, because the exponent is too large). Otherwise it returns 0
! 753: if the base is valid and if the entire string up to the final '\0' is
! 754: a valid number in base @var{base}, and 1 if the input is incorrect.
! 755: @end deftypefun
! 756:
! 757: @deftypefun void mpfr_set_str_raw (mpfr_t @var{x}, char *@var{s})
! 758: Set @var{x} to the value of the binary number in string @var{s}, which has to
! 759: be of the
! 760: form +/-xxxx.xxxxxxEyy. The exponent is read in decimal, but is interpreted
! 761: as the power of two to be multiplied by the mantissa.
! 762: The mantissa length of @var{s} has to be less or equal to the precision of
! 763: @var{x}, otherwise an error occurs.
! 764: If @var{s} starts with @code{N}, it is interpreted as NaN (Not-a-Number);
! 765: if it starts with @code{I} after the sign, it is interpreted as infinity,
! 766: with the corresponding sign.
! 767: @end deftypefun
! 768:
! 769: @deftypefun int mpfr_set_f (mpfr_t @var{x}, mpf_t @var{y}, mp_rnd_t @var{rnd})
! 770: Set @var{x} to the GNU MP floating-point number
! 771: @var{y}, rounded with the @var{rnd} mode and the precision
! 772: of @var{x}.
! 773: The returned value is zero when @var{x}=@var{y}, positive when @var{x}>@var{y},
! 774: and negative when @var{x}<@var{y}.
! 775: @end deftypefun
! 776:
! 777: @deftypefun void mpfr_set_inf (mpfr_t @var{x}, int @var{sign})
! 778: @deftypefunx void mpfr_set_nan (mpfr_t @var{x})
! 779: Set the variable @var{x} to infinity or NaN (Not-a-Number) respectively.
! 780: In @code{mpfr_set_inf}, @var{x} is set to plus infinity iff @var{sign} is
! 781: positive.
! 782: @end deftypefun
! 783:
! 784: @deftypefun void mpfr_swap (mpfr_t @var{x}, mpfr_t @var{y})
! 785: Swap the values @var{x} and @var{y} efficiently. Warning: the
! 786: precisions are exchanged too; in case the precisions are different,
! 787: @code{mpfr_swap} is thus not equivalent to three @code{mpfr_set} calls
! 788: using a third auxiliary variable.
! 789: @end deftypefun
! 790:
! 791: @node Simultaneous Float Init & Assign, Converting Floats, Assigning Floats, Floating-point Functions
! 792: @comment node-name, next, previous, up
! 793: @section Combined Initialization and Assignment Functions
! 794: @cindex Initialization and assignment functions
! 795:
! 796: @deftypefn Macro int mpfr_init_set (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 797: @deftypefnx Macro int mpfr_init_set_ui (mpfr_t @var{rop}, unsigned long int @var{op}, mp_rnd_t @var{rnd})
! 798: @deftypefnx Macro int mpfr_init_set_si (mpfr_t @var{rop}, signed long int @var{op}, mp_rnd_t @var{rnd})
! 799: @deftypefnx Macro int mpfr_init_set_d (mpfr_t @var{rop}, double @var{op}, mp_rnd_t @var{rnd})
! 800: @deftypefnx Macro int mpfr_init_set_f (mpfr_t @var{rop}, mpf_t @var{op}, mp_rnd_t @var{rnd})
! 801: @deftypefnx Macro int mpfr_init_set_z (mpfr_t @var{rop}, mpz_t @var{op}, mp_rnd_t @var{rnd})
! 802: @deftypefnx Macro int mpfr_init_set_q (mpfr_t @var{rop}, mpq_t @var{op}, mp_rnd_t @var{rnd})
! 803: Initialize @var{rop} and set its value from @var{op}, rounded to direction
! 804: @var{rnd}.
! 805: The precision of @var{rop} will be taken from the active default precision,
! 806: as set by @code{mpfr_set_default_prec}.
! 807: The return value if zero if @var{rop}=@var{op}, positive if @var{rop}>@var{op},
! 808: and negative when @var{rop}<@var{op}.
! 809: @end deftypefn
! 810:
! 811: @deftypefun int mpfr_init_set_str (mpfr_t @var{x}, char *@var{s}, int @var{base}, mp_rnd_t @var{rnd})
! 812: Initialize @var{x} and set its value from
! 813: the string @var{s} in base @var{base},
! 814: rounded to direction @var{rnd}.
! 815: See @code{mpfr_set_str}.
! 816: @end deftypefun
! 817:
! 818: @node Converting Floats, Float Arithmetic, Simultaneous Float Init & Assign, Floating-point Functions
! 819: @comment node-name, next, previous, up
! 820: @section Conversion Functions
! 821: @cindex Conversion functions
! 822:
! 823: @deftypefun double mpfr_get_d (mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 824: Convert @var{op} to a double, using the rounding mode @var{rnd}.
! 825: @end deftypefun
! 826:
! 827: @deftypefun double mpfr_get_d1 (mpfr_t @var{op})
! 828: Convert @var{op} to a double, using the default MPFR rounding mode
! 829: (see function @code{mpfr_set_default_rounding_mode}).
! 830: @end deftypefun
! 831:
! 832: @deftypefun mp_exp_t mpfr_get_z_exp (mpz_t @var{z}, mpfr_t @var{op})
! 833: Puts the mantissa of @var{op} into @var{z}, and returns the exponent
! 834: @var{exp} such that @var{op} equals @var{z} multiplied by two exponent
! 835: @var{exp}.
! 836: @end deftypefun
! 837:
! 838: @deftypefun {char *} mpfr_get_str (char *@var{str}, mp_exp_t *@var{expptr}, int @var{base}, size_t @var{n_digits}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 839: Convert @var{op} to a string of digits in base @var{base}, with rounding in
! 840: direction @var{rnd}. The base may vary
! 841: from 2 to 36. Generate exactly @var{n_digits} significant digits.
! 842:
! 843: If @var{n_digits} is 0, it writes the maximum possible number of digits
! 844: giving an exact rounding in the given base @var{base} with the direction
! 845: @var{rnd}. In other words, if @var{op} was the exact rounding
! 846: of a real number in direction @var{rnd}, then the written value is also
! 847: an exact rounding in base @var{base} of that real number with the same
! 848: precision. An error occurs when one is unable to determine the leading
! 849: digit, which can happen especially if the precision of @var{op} is small.
! 850:
! 851: If @var{str} is a null pointer, space for the mantissa is allocated using
! 852: the default allocation function, and a pointer to the string is returned.
! 853: In that case, the user should her/himself free the corresponding memory
! 854: with @code{(*_mp_free_func)(s, strlen(s) + 1)}.
! 855:
! 856: If @var{str} is not a null pointer, it should point to a block of storage
! 857: large enough for the mantissa, i.e., @var{n_digits} + 2 or more. The extra
! 858: two bytes are for a possible minus sign, and for the terminating null
! 859: character.
! 860:
! 861: If the input number is a real number, the exponent is written through
! 862: the pointer @var{expptr} (the current minimal exponent for 0).
! 863:
! 864: If @var{n_digits} is 0, note that the space requirements for @var{str}
! 865: in this case will be impossible for the user to predetermine. Therefore,
! 866: one needs to pass a null pointer for the string argument whenever
! 867: @var{n_digits} is 0.
! 868:
! 869: The generated string is a fraction, with an implicit radix point immediately
! 870: to the left of the first digit. For example, the number 3.1416 would be
! 871: returned as "31416" in the string and 1 written at @var{expptr}.
! 872:
! 873: A pointer to the string is returned, unless there is an error, in which
! 874: case a null pointer is returned.
! 875: @end deftypefun
! 876:
! 877:
! 878: @node Float Arithmetic, Float Comparison, Converting Floats, Floating-point Functions
! 879: @comment node-name, next, previous, up
! 880: @section Basic Arithmetic Functions
! 881: @cindex Float arithmetic functions
! 882: @cindex Arithmetic functions
! 883:
! 884: @deftypefun int mpfr_add (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mp_rnd_t @var{rnd})
! 885: @deftypefunx int mpfr_add_ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mp_rnd_t @var{rnd})
! 886: @deftypefunx int mpfr_add_z (mpfr_t @var{rop}, mpfr_t @var{op1}, mpz_t @var{op2}, mp_rnd_t @var{rnd})
! 887: @deftypefunx int mpfr_add_q (mpfr_t @var{rop}, mpfr_t @var{op1}, mpq_t @var{op2}, mp_rnd_t @var{rnd})
! 888: Set @var{rop} to @var{op1} @math{+} @var{op2} rounded in the direction @var{rnd}.
! 889: The return value is zero if @var{rop} is exactly @var{op1} @math{+} @var{op2},
! 890: positive if @var{rop} is larger than @var{op1} @math{+} @var{op2},
! 891: and negative if @var{rop} is smaller than @var{op1} @math{+} @var{op2}.
! 892: @end deftypefun
! 893:
! 894: @deftypefun int mpfr_sub (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mp_rnd_t @var{rnd})
! 895: @deftypefunx int mpfr_ui_sub (mpfr_t @var{rop}, unsigned long int @var{op1}, mpfr_t @var{op2}, mp_rnd_t @var{rnd})
! 896: @deftypefunx int mpfr_sub_ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mp_rnd_t @var{rnd})
! 897: @deftypefunx int mpfr_sub_z (mpfr_t @var{rop}, mpfr_t @var{op1}, mpz_t @var{op2}, mp_rnd_t @var{rnd})
! 898: @deftypefunx int mpfr_sub_q (mpfr_t @var{rop}, mpfr_t @var{op1}, mpq_t @var{op2}, mp_rnd_t @var{rnd})
! 899: Set @var{rop} to @var{op1} @minus{} @var{op2} rounded in the direction @var{rnd}.
! 900: The return value is zero if @var{rop} is exactly @var{op1} @minus{} @var{op2},
! 901: positive if @var{rop} is larger than @var{op1} @minus{} @var{op2},
! 902: and negative if @var{rop} is smaller than @var{op1} @minus{} @var{op2}.
! 903: @end deftypefun
! 904:
! 905: @deftypefun int mpfr_mul (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mp_rnd_t @var{rnd})
! 906: @deftypefunx int mpfr_mul_ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mp_rnd_t @var{rnd})
! 907: @deftypefunx int mpfr_mul_z (mpfr_t @var{rop}, mpfr_t @var{op1}, mpz_t @var{op2}, mp_rnd_t @var{rnd})
! 908: @deftypefunx int mpfr_mul_q (mpfr_t @var{rop}, mpfr_t @var{op1}, mpq_t @var{op2}, mp_rnd_t @var{rnd})
! 909: @ifinfo
! 910: Set @var{rop} to @var{op1} times @var{op2} rounded in the direction @var{rnd}.
! 911: Return 0 if the result is exact, a positive value if
! 912: @var{rop}>@var{op1}*@var{op2}, a negative value otherwise.
! 913: @end ifinfo
! 914: @tex
! 915: Set @var{rop} to $@var{op1} \times @var{op2}$ rounded in the direction @var{rnd}.
! 916: Return 0 if the result is exact, a positive value if
! 917: $@var{rop} > @var{op1} \times @var{op2}$, a negative value otherwise.
! 918: @end tex
! 919: @end deftypefun
! 920:
! 921: @deftypefun int mpfr_div (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mp_rnd_t @var{rnd})
! 922: @deftypefunx int mpfr_ui_div (mpfr_t @var{rop}, unsigned long int @var{op1}, mpfr_t @var{op2}, mp_rnd_t @var{rnd})
! 923: @deftypefunx int mpfr_div_ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mp_rnd_t @var{rnd})
! 924: @deftypefunx int mpfr_div_z (mpfr_t @var{rop}, mpfr_t @var{op1}, mpz_t @var{op2}, mp_rnd_t @var{rnd})
! 925: @deftypefunx int mpfr_div_q (mpfr_t @var{rop}, mpfr_t @var{op1}, mpq_t @var{op2}, mp_rnd_t @var{rnd})
! 926: Set @var{rop} to @var{op1}/@var{op2} rounded in the direction @var{rnd}.
! 927: These functions return 0 if the division is exact,
! 928: a positive value when @var{rop} is larger than @var{op1} divided by @var{op2},
! 929: and a negative value otherwise.
! 930: @end deftypefun
! 931:
! 932: @deftypefun int mpfr_sqrt (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 933: @deftypefunx int mpfr_sqrt_ui (mpfr_t @var{rop}, unsigned long int @var{op}, mp_rnd_t @var{rnd})
! 934: @ifinfo
! 935: Set @var{rop} to the square root of @var{op} rounded in the direction @var{rnd}.
! 936: @end ifinfo
! 937: @tex
! 938: Set @var{rop} to $\sqrt{@var{op}}$ rounded in the direction @var{rnd}.
! 939: @end tex
! 940: Set @var{rop} to NaN if @var{op} is negative.
! 941: Return 0 if the operation is exact, a non-zero value otherwise.
! 942: @end deftypefun
! 943:
! 944: @deftypefun int mpfr_pow_ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mp_rnd_t @var{rnd})
! 945: @deftypefunx int mpfr_ui_pow_ui (mpfr_t @var{rop}, unsigned long int @var{op1}, unsigned long int @var{op2}, mp_rnd_t @var{rnd})
! 946: Set @var{rop} to @var{op1} raised to @var{op2}. The computation is done by
! 947: binary exponentiation.
! 948: Return 0 if the result is exact, a non-zero value otherwise (but the sign
! 949: of the return value has no meaning).
! 950: @end deftypefun
! 951:
! 952: @deftypefun int mpfr_ui_pow (mpfr_t @var{rop}, unsigned long int @var{op1}, mpfr_t @var{op2}, mp_rnd_t @var{rnd})
! 953: Set @var{rop} to @var{op1} raised to @var{op2},
! 954: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 955: Return zero iff the result is exact, a positive value when the
! 956: result is greater than @var{op1} to the power @var{op2}, and a negative value
! 957: when it is smaller.
! 958: @end deftypefun
! 959:
! 960: @deftypefun int mpfr_pow_si (mpfr_t @var{rop}, mpfr_t @var{op1}, long int @var{op2}, mp_rnd_t @var{rnd})
! 961: Set @var{rop} to @var{op1} raised to the power @var{op2},
! 962: rounded to the direction @var{rnd} with the
! 963: precision of @var{rop}.
! 964: Return zero iff the result is exact.
! 965: @end deftypefun
! 966:
! 967: @deftypefun int mpfr_pow (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mp_rnd_t @var{rnd})
! 968: Set @var{rop} to @var{op1} raised to the power @var{op2},
! 969: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 970: If @var{op1} is negative then @var{rop} is set to NaN,
! 971: even if @var{op2} is an integer.
! 972: Return zero iff the result is exact.
! 973: @end deftypefun
! 974:
! 975: @deftypefun int mpfr_neg (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 976: Set @var{rop} to @minus{}@var{op} rounded in the direction @var{rnd}.
! 977: Just changes the sign
! 978: if @var{rop} and @var{op} are the same variable.
! 979: @end deftypefun
! 980:
! 981: @deftypefun int mpfr_abs (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 982: Set @var{rop} to the absolute value of @var{op},
! 983: rounded in the direction @var{rnd}.
! 984: Return 0 if the result is exact, a positive value if @var{rop} is larger than
! 985: the absolute value of @var{op}, and a negative value otherwise.
! 986: @end deftypefun
! 987:
! 988: @deftypefun int mpfr_mul_2exp (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mp_rnd_t @var{rnd})
! 989: @deftypefunx int mpfr_mul_2ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mp_rnd_t @var{rnd})
! 990: @deftypefunx int mpfr_mul_2si (mpfr_t @var{rop}, mpfr_t @var{op1}, long int @var{op2}, mp_rnd_t @var{rnd})
! 991: @ifinfo
! 992: Set @var{rop} to @var{op1} times 2 raised to @var{op2}
! 993: @end ifinfo
! 994: @tex
! 995: Set @var{rop} to $@var{op1} \times 2^{op2}$
! 996: @end tex
! 997: rounded to the direction @var{rnd}. Just increases the exponent by @var{op2}
! 998: when @var{rop} and @var{op1} are identical.
! 999: Return zero when @var{rop}=@var{op1}, a positive value when @var{rop}>@var{op1},
! 1000: and a negative value when @var{rop}<@var{op1}.
! 1001: Note: The @code{mpfr_mul_2exp} function is defined for compatibility reasons;
! 1002: you should use @code{mpfr_mul_2ui} (or @code{mpfr_mul_2si}) instead.
! 1003: @end deftypefun
! 1004:
! 1005: @deftypefun int mpfr_div_2exp (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mp_rnd_t @var{rnd})
! 1006: @deftypefunx int mpfr_div_2ui (mpfr_t @var{rop}, mpfr_t @var{op1}, unsigned long int @var{op2}, mp_rnd_t @var{rnd})
! 1007: @deftypefunx int mpfr_div_2si (mpfr_t @var{rop}, mpfr_t @var{op1}, long int @var{op2}, mp_rnd_t @var{rnd})
! 1008: @ifinfo
! 1009: Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}
! 1010: @end ifinfo
! 1011: @tex
! 1012: Set @var{rop} to $@var{op1}/2^{op2}$
! 1013: @end tex
! 1014: rounded to the direction @var{rnd}. Just decreases the exponent by @var{op2}
! 1015: when @var{rop} and @var{op1} are identical.
! 1016: Return zero when @var{rop}=@var{op1}, a positive value when @var{rop}>@var{op1},
! 1017: and a negative value when @var{rop}<@var{op1}.
! 1018: Note: The @code{mpfr_div_2exp} function is defined for compatibility reasons;
! 1019: you should use @code{mpfr_div_2ui} (or @code{mpfr_div_2si}) instead.
! 1020: @end deftypefun
! 1021:
! 1022: @node Float Comparison, I/O of Floats, Float Arithmetic, Floating-point Functions
! 1023: @comment node-name, next, previous, up
! 1024: @section Comparison Functions
! 1025: @cindex Float comparisons functions
! 1026: @cindex Comparison functions
! 1027:
! 1028: @deftypefun int mpfr_cmp (mpfr_t @var{op1}, mpfr_t @var{op2})
! 1029: @deftypefunx int mpfr_cmp_ui (mpfr_t @var{op1}, unsigned long int @var{op2})
! 1030: @deftypefunx int mpfr_cmp_si (mpfr_t @var{op1}, signed long int @var{op2})
! 1031: @ifinfo
! 1032: Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} >
! 1033: @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
! 1034: @var{op2}.
! 1035: @end ifinfo
! 1036: @tex
! 1037: Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} >
! 1038: @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
! 1039: < @var{op2}$.
! 1040: @end tex
! 1041: Both @var{op1} and @var{op2} are considered to their full own precision,
! 1042: which may differ. In case @var{op1} and @var{op2} are of same sign but
! 1043: different, the absolute value returned is
! 1044: one plus the absolute difference of their exponents.
! 1045: It is not allowed that one of the operands is NaN (Not-a-Number).
! 1046: @end deftypefun
! 1047:
! 1048: @deftypefun int mpfr_cmp_ui_2exp (mpfr_t @var{op1}, unsigned long int @var{op2}, int @var{e})
! 1049: @deftypefunx int mpfr_cmp_si_2exp (mpfr_t @var{op1}, long int @var{op2}, int @var{e})
! 1050: Compare @var{op1} and @var{op2} multiplied by two to the power @var{e}.
! 1051: @end deftypefun
! 1052:
! 1053: @deftypefun int mpfr_eq (mpfr_t @var{op1}, mpfr_t @var{op2}, unsigned long int op3)
! 1054: Return non-zero if the first @var{op3} bits of @var{op1} and @var{op2} are
! 1055: equal, zero otherwise. I.e., tests if @var{op1} and @var{op2} are
! 1056: approximately equal.
! 1057: @end deftypefun
! 1058:
! 1059: @deftypefun int mpfr_nan_p (mpfr_t @var{op})
! 1060: Return non-zero if @var{op} is Not-a-Number (NaN), zero otherwise.
! 1061: @end deftypefun
! 1062:
! 1063: @deftypefun int mpfr_inf_p (mpfr_t @var{op})
! 1064: Return non-zero if @var{op} is plus or minus infinity, zero otherwise.
! 1065: @end deftypefun
! 1066:
! 1067: @deftypefun int mpfr_number_p (mpfr_t @var{op})
! 1068: Return non-zero if @var{op} is an ordinary number, i.e. neither Not-a-Number
! 1069: nor plus or minus infinity.
! 1070: @end deftypefun
! 1071:
! 1072: @deftypefun void mpfr_reldiff (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mp_rnd_t @var{rnd})
! 1073: Compute the relative difference between @var{op1} and @var{op2}
! 1074: and store the result in @var{rop}.
! 1075: This function does not guarantee the exact rounding on the relative difference;
! 1076: it just computes abs(@var{op1}@minus{}@var{op2})/@var{op1}, using the
! 1077: rounding mode @var{rnd} for all operations.
! 1078: @end deftypefun
! 1079:
! 1080: @deftypefun int mpfr_sgn (mpfr_t @var{op})
! 1081: Return a positive value if @var{op} > 0, zero if @var{op} = 0,
! 1082: and a negative value if @var{op} < 0.
! 1083: Its result is not specified when @var{op} is NaN (Not-a-Number).
! 1084: @end deftypefun
! 1085:
! 1086: @section Special Functions
! 1087: @cindex Special functions
! 1088:
! 1089: @deftypefun int mpfr_log (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1090: Set @var{rop} to the natural logarithm of @var{op},
! 1091: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 1092: Return zero when the result is exact
! 1093: (this occurs in fact only when @var{op} is 0, 1, or +infinity)
! 1094: and a non-zero value otherwise (except for rounding to nearest,
! 1095: the sign of the return value is that of @var{rop}-log(@var{op}).
! 1096: @end deftypefun
! 1097:
! 1098: @deftypefun int mpfr_exp (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1099: Set @var{rop} to the exponential of @var{op},
! 1100: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 1101: Return zero when the result is exact
! 1102: (this occurs in fact only when @var{op} is -infinity, 0, or +infinity),
! 1103: a positive value when the result is greater than the exponential of @var{op},
! 1104: and a negative value when it is smaller.
! 1105: @end deftypefun
! 1106:
! 1107: @deftypefun int mpfr_exp2 (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1108: Set @var{rop} to 2 power of @var{op},
! 1109: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 1110: Return zero iff the result is exact (this occurs in fact only when @var{op}
! 1111: is -infinity, 0, or +infinity),
! 1112: a positive value when the result is greater than the exponential of @var{op},
! 1113: and a negative value when it is smaller.
! 1114: @end deftypefun
! 1115:
! 1116: @deftypefun int mpfr_cos (mpfr_t @var{cop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1117: @deftypefunx int mpfr_sin (mpfr_t @var{sop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1118: @deftypefunx int mpfr_tan (mpfr_t @var{top}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1119: Set @var{cop} to the cosine of @var{op}, @var{sop} to the sine of @var{op},
! 1120: @var{top} to the tangent of @var{op}, rounded to the direction @var{rnd} with
! 1121: the precision of @var{rop}. Return 0 iff the result is exact (this occurs
! 1122: in fact only when @var{op} is 0 i.e. the sine is 0, the cosine is 1, and the
! 1123: tangent is 0).
! 1124: @end deftypefun
! 1125:
! 1126: @deftypefun int mpfr_sin_cos (mpfr_t @var{sop}, mpfr_t @var{cop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1127: Set simultaneously @var{sop} to the sine of @var{op} and
! 1128: @var{cop} to the cosine of @var{op},
! 1129: rounded to the direction @var{rnd} with their corresponding precisions.
! 1130: Return 0 iff both results are exact.
! 1131: @end deftypefun
! 1132:
! 1133: @deftypefun int mpfr_acos (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1134: @deftypefunx int mpfr_asin (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1135: @deftypefunx int mpfr_atan (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1136: Set @var{rop} to the arc-cosine, arc-sine or arc-tangent of @var{op},
! 1137: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 1138: Return 0 iff the result is exact.
! 1139: @end deftypefun
! 1140:
! 1141: @deftypefun int mpfr_cosh (mpfr_t @var{cop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1142: @deftypefunx int mpfr_sinh (mpfr_t @var{sop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1143: @deftypefunx int mpfr_tanh (mpfr_t @var{top}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1144: Set @var{cop} to the hyperbolic cosine of @var{op},
! 1145: @var{sop} to the hyperbolic sine of @var{op},
! 1146: @var{top} to the hyperbolic tangent of @var{op},
! 1147: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 1148: Return 0 iff the result is exact (this occurs in fact only when @var{op} is 0
! 1149: i.e. the result is 1).
! 1150: @end deftypefun
! 1151:
! 1152: @deftypefun int mpfr_acosh (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1153: @deftypefunx int mpfr_asinh (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1154: @deftypefunx int mpfr_atanh (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1155: Set @var{rop} to the inverse hyperbolic cosine, sine or tangent of @var{op},
! 1156: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 1157: Return 0 iff the result is exact.
! 1158: @end deftypefun
! 1159:
! 1160: @deftypefun int mpfr_fac_ui (mpfr_t @var{rop}, unsigned long int @var{op}, mp_rnd_t @var{rnd})
! 1161: Set @var{rop} to the factorial of the unsigned long int @var{op},
! 1162: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 1163: Return 0 iff the result is exact.
! 1164: @end deftypefun
! 1165:
! 1166: @deftypefun int mpfr_log1p (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1167: Set @var{rop} to the logarithm of one plus @var{op},
! 1168: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 1169: Return 0 iff the result is exact (this occurs in fact only when @var{op} is 0
! 1170: i.e. the result is 0).
! 1171: @end deftypefun
! 1172:
! 1173: @deftypefun int mpfr_expm1 (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1174: Set @var{rop} to the exponential of @var{op} minus one,
! 1175: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 1176: Return 0 iff the result is exact (this occurs in fact only when @var{op} is 0
! 1177: i.e. the result is 0).
! 1178: @end deftypefun
! 1179:
! 1180: @deftypefun int mpfr_log2 (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1181: @deftypefunx int mpfr_log10 (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1182: Set @var{rop} to the log[t] (t=2 or 10)(log x / log t) of @var{op}, rounded to the direction @var{rnd} with the precision of @var{rop}. Return 0 iff the result is exact (this occurs in fact only when @var{op} is 1 i.e. the result is 0).
! 1183: @end deftypefun
! 1184:
! 1185: @deftypefun int mpfr_fma (mpfr_t @var{rop}, mpfr_t @var{opx},mpfr_t @var{opy},mpfr_t @var{opz}, mp_rnd_t @var{rnd})
! 1186: Set @var{rop} to @var{opx} * @var{opy} + @var{opz}, rounded to the direction
! 1187: @var{rnd} with the precision of @var{rop}. Return 0 iff the result is exact,
! 1188: a positive value if @var{rop} is larger than @var{opx} * @var{opy} + @var{opz},
! 1189: and a negative value otherwise.
! 1190: @end deftypefun
! 1191:
! 1192: @deftypefun void mpfr_agm (mpfr_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mp_rnd_t @var{rnd})
! 1193: Set @var{rop} to the arithmetic-geometric mean of @var{op1} and @var{op2},
! 1194: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 1195: @end deftypefun
! 1196:
! 1197: @deftypefun void mpfr_const_log2 (mpfr_t @var{rop}, mp_rnd_t @var{rnd})
! 1198: Set @var{rop} to the logarithm of 2 rounded to the direction @var{rnd}
! 1199: with the precision of @var{rop}. This function stores the computed
! 1200: value to avoid another calculation if a lower or equal precision is
! 1201: requested.
! 1202: @end deftypefun
! 1203:
! 1204: @deftypefun void mpfr_const_pi (mpfr_t @var{rop}, mp_rnd_t @var{rnd})
! 1205: Set @var{rop} to the value of Pi rounded to the direction @var{rnd}
! 1206: with the precision of @var{rop}. This function uses the Borwein, Borwein,
! 1207: Plouffe formula which directly gives the expansion of Pi in base 16.
! 1208: @end deftypefun
! 1209:
! 1210: @deftypefun void mpfr_const_euler (mpfr_t @var{rop}, mp_rnd_t @var{rnd})
! 1211: Set @var{rop} to the value of Euler's constant 0.577...
! 1212: rounded to the direction @var{rnd} with the precision of @var{rop}.
! 1213: @end deftypefun
! 1214:
! 1215: @node I/O of Floats, Miscellaneous Float Functions, Float Comparison, Floating-point Functions
! 1216: @comment node-name, next, previous, up
! 1217: @section Input and Output Functions
! 1218: @cindex Float input and output functions
! 1219: @cindex Input functions
! 1220: @cindex Output functions
! 1221: @cindex I/O functions
! 1222:
! 1223: Functions that perform input from a standard input/output
! 1224: stream, and functions that output to
! 1225: a standard input/output stream.
! 1226: Passing a null pointer for a @var{stream} argument to any of
! 1227: these functions will make them read from @code{stdin} and write to
! 1228: @code{stdout}, respectively.
! 1229:
! 1230: When using any of these functions, it is a good idea to include @file{stdio.h}
! 1231: before @file{mpfr.h}, since that will allow @file{mpfr.h} to define prototypes
! 1232: for these functions.
! 1233:
! 1234: @deftypefun size_t mpfr_out_str (FILE *@var{stream}, int @var{base}, size_t @var{n_digits}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1235: Output @var{op} on stdio stream @var{stream}, as a string of digits in
! 1236: base @var{base}, rounded to direction @var{rnd}.
! 1237: The base may vary from 2 to 36. Print at most
! 1238: @var{n_digits} significant digits, or if @var{n_digits} is 0, the maximum
! 1239: number of digits accurately representable by @var{op}.
! 1240:
! 1241: In addition to the significant digits, a decimal point at the right of the
! 1242: first digit and a
! 1243: trailing exponent, in the form @samp{eNNN}, are printed. If @var{base}
! 1244: is greater than 10, @samp{@@} will be used instead of @samp{e} as
! 1245: exponent delimiter.
! 1246:
! 1247: Return the number of bytes written, or if an error occurred, return 0.
! 1248: @end deftypefun
! 1249:
! 1250: @deftypefun size_t mpfr_inp_str (mpfr_t @var{rop}, FILE *@var{stream}, int @var{base}, mp_rnd_t @var{rnd})
! 1251: Input a string in base @var{base} from stdio stream @var{stream},
! 1252: rounded in direction @var{rnd}, and put the
! 1253: read float in @var{rop}. The string is of the form @samp{M@@N} or, if the
! 1254: base is 10 or less, alternatively @samp{MeN} or @samp{MEN}.
! 1255: @samp{M} is the mantissa and
! 1256: @samp{N} is the exponent. The mantissa is always in the specified base. The
! 1257: exponent is
! 1258: @c either in the specified base or, if @var{base} is negative,
! 1259: in decimal.
! 1260:
! 1261: The argument @var{base} may be in the range 2 to 36.
! 1262: @c , or @minus{}36 to
! 1263: @c @minus{}2. Negative values are used to specify that the exponent is in
! 1264: @c decimal.
! 1265:
! 1266: Unlike the corresponding @code{mpz} function, the base will not be determined
! 1267: from the leading characters of the string if @var{base} is 0. This is so that
! 1268: numbers like @samp{0.23} are not interpreted as octal.
! 1269:
! 1270: Return the number of bytes read, or if an error occurred, return 0.
! 1271: @end deftypefun
! 1272:
! 1273: @deftypefun void mpfr_print_binary (mpfr_t @var{float})
! 1274: Output @var{float} on stdout
! 1275: in raw binary format (the exponent is in decimal, yet).
! 1276: The last bits from the least significant limb which do not belong to
! 1277: the mantissa are printed between square brackets;
! 1278: they should always be zero.
! 1279: @end deftypefun
! 1280:
! 1281: @c @deftypefun void mpfr_inp_raw (mpfr_t @var{float}, FILE *@var{stream})
! 1282: @c Input from stdio stream @var{stream} in the format written by
! 1283: @c @code{mpfr_out_raw}, and put the result in @var{float}.
! 1284: @c @end deftypefun
! 1285:
! 1286:
! 1287: @node Miscellaneous Float Functions, , I/O of Floats, Floating-point Functions
! 1288: @comment node-name, next, previous, up
! 1289: @section Miscellaneous Functions
! 1290: @cindex Miscellaneous float functions
! 1291:
! 1292: @deftypefun int mpfr_rint (mpfr_t @var{rop}, mpfr_t @var{op}, mp_rnd_t @var{rnd})
! 1293: @deftypefunx int mpfr_ceil (mpfr_t @var{rop}, mpfr_t @var{op})
! 1294: @deftypefunx int mpfr_floor (mpfr_t @var{rop}, mpfr_t @var{op})
! 1295: @deftypefunx int mpfr_round (mpfr_t @var{rop}, mpfr_t @var{op})
! 1296: @deftypefunx int mpfr_trunc (mpfr_t @var{rop}, mpfr_t @var{op})
! 1297: Set @var{rop} to @var{op} rounded to an integer. @code{mpfr_ceil} rounds
! 1298: to the next higher representable integer, @code{mpfr_floor} to the next lower,
! 1299: @code{mpfr_round} to the nearest representable integer, rounding halfway cases
! 1300: away from zero, and @code{mpfr_trunc} to the representable integer towards
! 1301: zero. @code{mpfr_rint} behaves like one of these four functions, depending
! 1302: on the rounding mode.
! 1303: The returned value is zero when the result is exact, positive when it is
! 1304: greater than the original value of @var{op}, and negative when it is smaller.
! 1305: More precisely, the returned value is 0 when @var{op} is an integer
! 1306: representable in @var{rop}, 1 or @minus{}1 when @var{op} is an integer
! 1307: that is not representable in @var{rop}, 2 or @minus{}2 when @var{op} is
! 1308: not an integer.
! 1309: @end deftypefun
! 1310:
! 1311: @deftypefun void mpfr_urandomb (mpfr_t @var{rop}, gmp_randstate_t @var{state})
! 1312: Generate a uniformly distributed random float in the interval 0 <= X < 1.
! 1313: @end deftypefun
! 1314:
! 1315: @deftypefun void mpfr_random (mpfr_t @var{rop})
! 1316: Generate a uniformly distributed random float in the interval 0 <= X < 1.
! 1317: @end deftypefun
! 1318:
! 1319: @deftypefun void mpfr_random2 (mpfr_t @var{rop}, mp_size_t @var{max_size}, mp_exp_t @var{max_exp})
! 1320: Generate a random float of at most @var{max_size} limbs, with long strings of
! 1321: zeros and ones in the binary representation. The exponent of the number is in
! 1322: the interval @minus{}@var{exp} to @var{exp}.
! 1323: This function is useful for
! 1324: testing functions and algorithms, since this kind of random numbers have
! 1325: proven to be more likely to trigger corner-case bugs.
! 1326: Negative random numbers are generated when @var{max_size} is negative.
! 1327: @end deftypefun
! 1328:
! 1329: @c @deftypefun size_t mpfr_size (mpfr_t @var{op})
! 1330: @c Return the size of @var{op} measured in number of limbs. If @var{op} is
! 1331: @c zero, the returned value will be zero. (@xref{Nomenclature}, for an
! 1332: @c explanation of the concept @dfn{limb}.)
! 1333: @c
! 1334: @c @strong{This function is obsolete. It will disappear from future MP
! 1335: @c releases.}
! 1336: @c @end deftypefun
! 1337:
! 1338: @section Internals
! 1339:
! 1340: These types and
! 1341: functions were mainly designed for the implementation of @code{mpfr},
! 1342: but may be useful for users too.
! 1343: However no upward compatibility is guaranteed.
! 1344: You need to include @code{mpfr-impl.h} to use them.
! 1345:
! 1346: The @code{mpfr_t} type consists of four fields.
! 1347: The @code{_mpfr_prec} field is used to store the precision of
! 1348: the variable (in bits); this is not less than 2.
! 1349:
! 1350: The @code{_mpfr_size} field is used to store the number of
! 1351: allocated limbs, with the high bits reserved to store
! 1352: the sign (bit 31), the NaN flag (bit 30),
! 1353: and the Infinity flag (bit 29);
! 1354: thus bits 0 to 28 remain for the number of allocated limbs, with a maximal
! 1355: value of 536870911.
! 1356: A NaN is indicated by the NaN flag set, and no other fields are
! 1357: relevant.
! 1358: An Infinity is indicated by the NaN flag clear and the Inf flag set;
! 1359: the sign bit of an Infinity indicates the sign, the limb data
! 1360: and the exponent are not relevant.
! 1361:
! 1362: The @code{_mpfr_exp} field stores the exponent.
! 1363: An exponent of 0 means a radix point just above the most significant
! 1364: limb. Non-zero values are a multiplier @math{2^n} relative to that
! 1365: point.
! 1366:
! 1367: Finally, the @code{_mpfr_d} is a pointer to the limbs, least
! 1368: significant limbs stored first.
! 1369: The number zero is represented with its most significant limb set to zero,
! 1370: i.e. @code{_mpfr_d[n-1]} where
! 1371: n=ceil(@code{_mpfr_prec}/@code{BITS_PER_MP_LIMB}).
! 1372: The number of limbs in use is controlled by @code{_mpfr_prec}, namely
! 1373: ceil(@code{_mpfr_prec}/@code{BITS_PER_MP_LIMB}).
! 1374: Zero is represented by the most significant limb being zero, other
! 1375: limb data and the exponent are not relevant
! 1376: ("not relevant" implies that the corresponding objects may contain
! 1377: invalid values, thus should not be evaluated even if
! 1378: they are not taken into account).
! 1379: Non-zero values always have the most significant bit of the most
! 1380: significant limb set to 1. When the precision is not a whole number
! 1381: of limbs, the excess bits at the low end of the data are zero.
! 1382: When the precision has been lowered by @code{mpfr_set_prec}, the space
! 1383: allocated at @code{_mpfr_d} remains as given by @code{_mpfr_size}, but
! 1384: @code{_mpfr_prec} indicates how much of that space is actually used.
! 1385:
! 1386: @deftypefun int mpfr_add_one_ulp (mpfr_t @var{x}, mp_rnd_t @var{rnd})
! 1387: Add one unit in last place (ulp) to @var{x} if @var{x} is finite
! 1388: and positive, subtract one ulp if @var{x} is finite and negative;
! 1389: otherwise, @var{x} is not changed.
! 1390: The return value is zero unless an overflow occurs, in which case the
! 1391: @code{mpfr_add_one_ulp} function behaves like a conventional addition.
! 1392: @end deftypefun
! 1393:
! 1394: @deftypefun int mpfr_sub_one_ulp (mpfr_t @var{x}, mp_rnd_t @var{rnd})
! 1395: Subtract one ulp to @var{x} if @var{x} is finite and positive, add one
! 1396: ulp if @var{x} is finite and negative; otherwise, @var{x} is not changed.
! 1397: The return value is zero unless an underflow occurs, in which case the
! 1398: @code{mpfr_sub_one_ulp} function behaves like a conventional subtraction.
! 1399: @end deftypefun
! 1400:
! 1401: @deftypefun int mpfr_can_round (mpfr_t @var{b}, mp_exp_t @var{err}, mp_rnd_t @var{rnd1}, mp_rnd_t @var{rnd2}, mp_prec_t @var{prec})
! 1402: Assuming @var{b} is an approximation of an unknown number
! 1403: @var{x} in direction @var{rnd1} with error at most two to the power
! 1404: E(b)-@var{err} where E(b) is the exponent of
! 1405: @var{b}, returns 1 if one is able to round exactly @var{x} to precision
! 1406: @var{prec} with direction @var{rnd2},
! 1407: and 0 otherwise. This function @strong{does not modify} its arguments.
! 1408: @end deftypefun
! 1409:
! 1410: @node Contributors, References, Floating-point Functions, Top
! 1411: @comment node-name, next, previous, up
! 1412: @unnumbered Contributors
! 1413:
! 1414: The main developers consist of Guillaume Hanrot, Vincent Lefèvre and
! 1415: Paul Zimmermann.
! 1416:
! 1417: We would like to thank Jean-Michel Muller and Joris van der Hoeven for very
! 1418: fruitful discussions at the beginning of that project, Torbjorn Granlund
! 1419: and Kevin Ryde
! 1420: for their help about design issues
! 1421: and their suggestions for an easy integration into GNU MP,
! 1422: and Nathalie Revol for her careful reading of this documentation.
! 1423:
! 1424: Sylvie Boldo from ENS-Lyon, France,
! 1425: contributed the functions @code{mpfr_agm} and @code{mpfr_log}.
! 1426: Emmanuel Jeandel, from ENS-Lyon too,
! 1427: contributed the generic hypergeometric code in
! 1428: @code{generic.c}, as well as the @code{mpfr_exp3},
! 1429: a first implementation of the sine and cosine,
! 1430: and improved versions of
! 1431: @code{mpfr_const_log2} and @code{mpfr_const_pi}.
! 1432: Mathieu Dutour contributed the functions @code{mpfr_atan} and @code{mpfr_asin},
! 1433: David Daney contributed the hyperbolic and inverse hyperbolic functions,
! 1434: the base-2 exponential, and the factorial function. Fabrice Rouillier
! 1435: contributed the original version of @file{mul_ui.c}, the @file{gmp_op.c}
! 1436: file, and helped to the Windows porting.
! 1437:
! 1438: @node References, Concept Index, Contributors, Top
! 1439: @comment node-name, next, previous, up
! 1440: @unnumbered References
! 1441:
! 1442: @itemize @bullet
! 1443:
! 1444: @item
! 1445: Torbjorn Granlund, "GNU MP: The GNU Multiple Precision Arithmetic Library",
! 1446: version 4.0.1, 2001.
! 1447:
! 1448: @item
! 1449: IEEE standard for binary floating-point arithmetic, Technical Report
! 1450: ANSI-IEEE Standard 754-1985, New York, 1985.
! 1451: Approved March 21, 1985: IEEE Standards Board; approved July 26,
! 1452: 1985: American National Standards Institute, 18 pages.
! 1453:
! 1454: @item
! 1455: Donald E. Knuth, "The Art of Computer Programming", vol 2,
! 1456: "Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981.
! 1457:
! 1458: @end itemize
! 1459:
! 1460: @node Concept Index, Function Index, References, Top
! 1461: @comment node-name, next, previous, up
! 1462: @unnumbered Concept Index
! 1463: @printindex cp
! 1464:
! 1465: @node Function Index, , Concept Index, Top
! 1466: @comment node-name, next, previous, up
! 1467: @unnumbered Function and Type Index
! 1468: @printindex fn
! 1469:
! 1470: @contents
! 1471: @bye
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to mpfr.texi CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gmp / mpfr