[BACK]Return to gmp.texi CVS log [TXT][DIR] Up to [local] / OpenXM / src / kan96xx / gmp-2.0.2

Annotation of OpenXM/src/kan96xx/gmp-2.0.2/gmp.texi, Revision 1.1.1.1

1.1       maekawa     1: \input texinfo    @c -*-texinfo-*-
                      2: @c %**start of header
                      3: @setfilename gmp.info
                      4: @settitle GNU MP 2.0.2
                      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: * gmp: (gmp.info).               GNU Multiple Precision Arithmetic 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 GNU MP, a library for arbitrary-precision arithmetic.
                     34:
                     35: Copyright (C) 1991, 1993, 1994, 1995, 1996 Free Software Foundation, Inc.
                     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 GNU MP
                     64: @subtitle The GNU Multiple Precision Arithmetic Library
                     65: @subtitle Edition 2.0.2
                     66: @subtitle June 1996
                     67:
                     68: @author by Torbj@"orn Granlund, TMG Datakonsult
                     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{} 1991, 1993, 1994, 1995, 1996 Free Software Foundation, Inc.
                     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 GNU MP
                    109:
                    110: This manual documents how to install and use the GNU multiple precision
                    111: arithmetic library, version 2.0.2.
                    112:
                    113: @end ifinfo
                    114:
                    115: @menu
                    116: * Copying::                   GMP Copying Conditions (LGPL).
                    117: * Introduction to MP::        Brief introduction to GNU MP.
                    118: * Installing MP::             How to configure and compile the MP library.
                    119: * MP Basics::                 What every MP user should now.
                    120: * Reporting Bugs::            How to usefully report bugs.
                    121: * Integer Functions::         Functions for arithmetic on signed integers.
                    122: * Rational Number Functions:: Functions for arithmetic on rational numbers.
                    123: * Floating-point Functions::  Functions for arithmetic on floats.
                    124: * Low-level Functions::       Fast functions for natural numbers.
                    125: * BSD Compatible Functions::  All functions found in BSD MP.
                    126: * Custom Allocation::         How to customize the internal allocation.
                    127:
                    128: * Contributors::
                    129: * References::
                    130: * Concept Index::
                    131: * Function Index::
                    132: @end menu
                    133:
                    134: @node Copying, Introduction to MP, Top, Top
                    135: @comment  node-name, next, previous,  up
                    136: @unnumbered GNU MP Copying Conditions
                    137: @cindex Copying conditions
                    138: @cindex Conditions for copying GNU MP
                    139:
                    140: This library is @dfn{free}; this means that everyone is free to use it and
                    141: free to redistribute it on a free basis.  The library is not in the public
                    142: domain; it is copyrighted and there are restrictions on its distribution, but
                    143: these restrictions are designed to permit everything that a good cooperating
                    144: citizen would want to do.  What is not allowed is to try to prevent others
                    145: from further sharing any version of this library that they might get from
                    146: you.@refill
                    147:
                    148: Specifically, we want to make sure that you have the right to give away copies
                    149: of the library, that you receive source code or else can get it if you want
                    150: it, that you can change this library or use pieces of it in new free programs,
                    151: and that you know you can do these things.@refill
                    152:
                    153: To make sure that everyone has such rights, we have to forbid you to deprive
                    154: anyone else of these rights.  For example, if you distribute copies of the GNU
                    155: MP library, you must give the recipients all the rights that you have.  You
                    156: must make sure that they, too, receive or can get the source code.  And you
                    157: must tell them their rights.@refill
                    158:
                    159: Also, for our own protection, we must make certain that everyone finds out
                    160: that there is no warranty for the GNU MP library.  If it is modified by
                    161: someone else and passed on, we want their recipients to know that what they
                    162: have is not what we distributed, so that any problems introduced by others
                    163: will not reflect on our reputation.@refill
                    164:
                    165: The precise conditions of the license for the GNU MP library are found in the
                    166: Library General Public License that accompany the source code.@refill
                    167:
                    168: @node Introduction to MP, Installing MP, Copying, Top
                    169: @comment  node-name,  next,  previous,  up
                    170: @chapter Introduction to GNU MP
                    171:
                    172:
                    173: GNU MP is a portable library written in C for arbitrary precision arithmetic
                    174: on integers, rational numbers, and floating-point numbers.  It aims to provide
                    175: the fastest possible arithmetic for all applications that need higher
                    176: precision than is directly supported by the basic C types.
                    177:
                    178: Many applications use just a few hundred bits of precision; but some
                    179: applications may need thousands or even millions of bits.  MP is designed to
                    180: give good performance for both, by choosing algorithms based on the sizes of
                    181: the operands, and by carefully keeping the overhead at a minimum.
                    182:
                    183: The speed of MP is achieved by using fullwords as the basic arithmetic type,
                    184: by using sophisticated algorithms, by including carefully optimized assembly
                    185: code for the most common inner loops for many different CPUs, and by a general
                    186: emphasis on speed (as opposed to simplicity or elegance).
                    187:
                    188: There is carefully optimized assembly code for these CPUs: DEC Alpha, Amd
                    189: 29000, HPPA 1.0 and 1.1, Intel Pentium and generic x86, Intel i960, Motorola
                    190: MC68000, MC68020, MC88100, and MC88110, Motorola/IBM PowerPC, National
                    191: NS32000, IBM POWER, MIPS R3000, R4000, SPARCv7, SuperSPARC, generic SPARCv8,
                    192: and DEC VAX.  Some optimizations also for ARM, Clipper, IBM ROMP (RT), and
                    193: Pyramid AP/XP.
                    194:
                    195: This version of MP is released under a more liberal license than previous
                    196: versions.  It is now permitted to link MP to non-free programs, as long as MP
                    197: source code is provided when distributing the non-free program.
                    198:
                    199:
                    200: @section How to use this Manual
                    201:
                    202: Everyone should read @ref{MP Basics}.  If you need to install the library
                    203: yourself, you need to read @ref{Installing MP}, too.
                    204:
                    205: The rest of the manual can be used for later reference, although it is
                    206: probably a good idea to glance through it.
                    207:
                    208:
                    209: @node Installing MP, MP Basics, Introduction to MP, Top
                    210: @comment  node-name,  next,  previous,  up
                    211: @chapter Installing MP
                    212: @cindex Installation
                    213:
                    214: To build MP, you first have to configure it for your CPU and operating system.
                    215: You need a C compiler, preferably GCC, but any reasonable compiler should
                    216: work.  And you need a standard Unix @samp{make} program, plus some other
                    217: standard Unix utility programs.
                    218:
                    219: (If you're on an MS-DOS machine, your can build MP using @file{make.bat}.  It
                    220: requires that djgpp is installed.  It does not require configuration, nor is
                    221: @samp{make} needed; @file{make.bat} both configures and builds the library.)
                    222:
                    223: Here are the steps needed to install the library on Unix systems:
                    224:
                    225: @enumerate
                    226: @item
                    227: In most cases, @samp{./configure --target=cpu-vendor-os}, should work both for
                    228: native and cross-compilation.  If you get error messages, your machine might
                    229: not be supported.
                    230:
                    231: If you want to compile in a separate object directory, cd to that directory,
                    232: and prefix the configure command with the path to the MP source directory.
                    233: Not all @samp{make} programs have the necessary features to support this.  In
                    234: particular, SunOS and Slowaris @samp{make} have bugs that makes them unable to
                    235: build from a separate object directory.  Use GNU @samp{make} instead.
                    236:
                    237: In addition to the standard cpu-vendor-os tuples, MP recognizes sparc8 and
                    238: supersparc as valid CPU names.  Specifying these CPU names for relevant
                    239: systems will improve performance significantly.
                    240:
                    241: In general, if you want a library that runs as fast as possible, you should
                    242: make sure you configure MP for the exact CPU type your system uses.
                    243:
                    244: If you have @code{gcc} in your @code{PATH}, it will be used by default.  To
                    245: override this, pass @samp{-with-gcc=no} to @file{configure}.
                    246:
                    247: @item
                    248: @samp{make}
                    249:
                    250: This will compile MP, and create a library archive file @file{libgmp.a} in the
                    251: working directory.
                    252:
                    253: @item
                    254: @samp{make check}
                    255:
                    256: This will make sure MP was built correctly.  If you get error messages, please
                    257: report this to @samp{bug-gmp@@prep.ai.mit.edu}.  (@xref{Reporting Bugs}, for
                    258: information on what to include in useful bug reports.)
                    259:
                    260: @item
                    261: @samp{make install}
                    262:
                    263: This will copy the file @file{gmp.h} and @file{libgmp.a}, as well as the info
                    264: files, to @file{/usr/local} (or if you passed the @samp{--prefix} option to
                    265: @file{configure}, to the directory given as argument to @samp{--prefix}).
                    266: @end enumerate
                    267:
                    268: @noindent
                    269: If you wish to build and install the BSD MP compatible functions, use
                    270: @samp{make libmp.a} and @samp{make install-bsdmp}.
                    271:
                    272: There are some other useful make targets:
                    273:
                    274: @itemize @bullet
                    275: @item
                    276: @samp{doc}
                    277:
                    278: Create a DVI version of the manual, in @file{gmp.dvi} and a set of info files,
                    279: in @file{gmp.info}, @file{gmp.info-1}, @file{gmp.info-2}, etc.
                    280:
                    281: @item
                    282: @samp{ps}
                    283:
                    284: Create a Postscript version of the manual, in @file{gmp.ps}.
                    285:
                    286: @item
                    287: @samp{html}
                    288:
                    289: Create a HTML version of the manual, in @file{gmp.html}.
                    290:
                    291: @item
                    292: @samp{clean}
                    293:
                    294: Delete all object files and archive files, but not the configuration files.
                    295:
                    296: @item
                    297: @samp{distclean}
                    298:
                    299: Delete all files not included in the distribution.
                    300:
                    301: @item
                    302: @samp{uninstall}
                    303:
                    304: Delete all files copied by @samp{make install}.
                    305: @end itemize
                    306:
                    307:
                    308: @section Known Build Problems
                    309:
                    310: GCC 2.7.2 (as well as 2.6.3) for the RS/6000 and PowerPC can not be used to
                    311: compile MP, due to a bug in GCC.  If you want to use GCC for these machines,
                    312: you need to apply the patch below to GCC, or use a later version of the
                    313: compiler.
                    314:
                    315: If you are on a Sequent Symmetry, use the GNU assembler instead of the
                    316: system's assembler, since the latter has serious bugs.
                    317:
                    318: The system compiler on NeXT is a massacred and old gcc, even if the compiler
                    319: calls itself @file{cc}.  This compiler cannot be used to build MP.  You need
                    320: to get a real gcc, and install that before you compile MP.  (NeXT might have
                    321: fixed this in newer releases of their system.)
                    322:
                    323: The system C compiler under SunOS 4 has a bug that makes it miscompile
                    324: mpq/get_d.c.  This will make @samp{make check} fail.
                    325:
                    326: Please report other problems to @samp{bug-gmp@@prep.ai.mit.edu}.
                    327: @xref{Reporting Bugs}.
                    328:
                    329:
                    330: Patch to apply to GCC 2.6.3 and 2.7.2:
                    331:
                    332: @example
                    333: *** config/rs6000/rs6000.md    Sun Feb 11 08:22:11 1996
                    334: --- config/rs6000/rs6000.md.new        Sun Feb 18 03:33:37 1996
                    335: ***************
                    336: *** 920,926 ****
                    337:      (set (match_operand:SI 0 "gpc_reg_operand" "=r")
                    338:        (not:SI (match_dup 1)))]
                    339:     ""
                    340: !   "nor. %0,%2,%1"
                    341:     [(set_attr "type" "compare")])
                    342:
                    343:   (define_insn ""
                    344: --- 920,926 ----
                    345:      (set (match_operand:SI 0 "gpc_reg_operand" "=r")
                    346:        (not:SI (match_dup 1)))]
                    347:     ""
                    348: !   "nor. %0,%1,%1"
                    349:     [(set_attr "type" "compare")])
                    350:
                    351:   (define_insn ""
                    352: @end example
                    353:
                    354: @node MP Basics, Reporting Bugs, Installing MP, Top
                    355: @comment  node-name,  next,  previous,  up
                    356: @chapter MP Basics
                    357:
                    358:
                    359: @cindex @file{gmp.h}
                    360: All declarations needed to use MP are collected in the include file
                    361: @file{gmp.h}.  It is designed to work with both C and C++ compilers.
                    362:
                    363:
                    364: @section Nomenclature and Types
                    365:
                    366: @cindex Integer
                    367: @tindex @code{mpz_t}
                    368: @noindent
                    369: In this manual, @dfn{integer} usually means a multiple precision integer, as
                    370: defined by the MP library.  The C data type for such integers is @code{mpz_t}.
                    371: Here are some examples of how to declare such integers:
                    372:
                    373: @example
                    374: mpz_t sum;
                    375:
                    376: struct foo @{ mpz_t x, y; @};
                    377:
                    378: mpz_t vec[20];
                    379: @end example
                    380:
                    381: @cindex Rational number
                    382: @tindex @code{mpq_t}
                    383: @noindent
                    384: @dfn{Rational number} means a multiple precision fraction.  The C data type
                    385: for these fractions is @code{mpq_t}.  For example:
                    386:
                    387: @example
                    388: mpq_t quotient;
                    389: @end example
                    390:
                    391: @cindex Floating-point number
                    392: @tindex @code{mpf_t}
                    393: @noindent
                    394: @dfn{Floating point number} or @dfn{Float} for short, is an arbitrary precision
                    395: mantissa with an limited precision exponent.  The C data type for such objects
                    396: is @code{mpf_t}.
                    397:
                    398: @cindex Limb
                    399: @tindex @code{mp_limb_t}
                    400: @noindent
                    401: A @dfn{limb} means the part of a multi-precision number that fits in a single
                    402: word.  (We chose this word because a limb of the human body is analogous to a
                    403: digit, only larger, and containing several digits.)  Normally a limb contains
                    404: 32 or 64 bits.  The C data type for a limb is @code{mp_limb_t}.
                    405:
                    406:
                    407: @section Function Classes
                    408:
                    409: There are six classes of functions in the MP library:
                    410:
                    411: @enumerate
                    412: @item
                    413: Functions for signed integer arithmetic, with names beginning with
                    414: @code{mpz_}.  The associated type is @code{mpz_t}.  There are about 100
                    415: functions in this class.
                    416:
                    417: @item
                    418: Functions for rational number arithmetic, with names beginning with
                    419: @code{mpq_}.  The associated type is @code{mpq_t}.  There are about 20
                    420: functions in this class, but the functions in the previous class can be used
                    421: for performing arithmetic on the numerator and denominator separately.
                    422:
                    423: @item
                    424: Functions for floating-point arithmetic, with names beginning with
                    425: @code{mpf_}.  The associated type is @code{mpf_t}.  There are about 50
                    426: functions is this class.
                    427:
                    428: @item
                    429: Functions compatible with Berkeley MP, such as @code{itom}, @code{madd}, and
                    430: @code{mult}.  The associated type is @code{MINT}.
                    431:
                    432: @item
                    433: Fast low-level functions that operate on natural numbers.  These are used by
                    434: the functions in the preceding groups, and you can also call them directly
                    435: from very time-critical user programs.  These functions' names begin with
                    436: @code{mpn_}.  There are about 30 (hard-to-use) functions in this class.
                    437:
                    438: The associated type is array of @code{mp_limb_t}.
                    439:
                    440: @item
                    441: Miscellaneous functions.  Functions for setting up custom allocation.
                    442: @end enumerate
                    443:
                    444:
                    445: @section MP Variable Conventions
                    446:
                    447: As a general rule, all MP functions expect output arguments before input
                    448: arguments.  This notation is based on an analogy with the assignment operator.
                    449: (The BSD MP compatibility functions disobey this rule, having the output
                    450: argument(s) last.)
                    451:
                    452: MP allows you to use the same variable for both input and output in the same
                    453: expression.  For example, the main function for integer multiplication,
                    454: @code{mpz_mul}, can be used like this: @code{mpz_mul (x, x, x)}.  This
                    455: computes the square of @var{x} and puts the result back in @var{x}.
                    456:
                    457: Before you can assign to an MP variable, you need to initialize it by calling
                    458: one of the special initialization functions.  When you're done with a
                    459: variable, you need to clear it out, using one of the functions for that
                    460: purpose.  Which function to use depends on the type of variable.  See the
                    461: chapters on integer functions, rational number functions, and floating-point
                    462: functions for details.
                    463:
                    464: A variable should only be initialized once, or at least cleared out between
                    465: each initialization.  After a variable has been initialized, it may be
                    466: assigned to any number of times.
                    467:
                    468: For efficiency reasons, avoid to initialize and clear out a variable in loops.
                    469: Instead, initialize it before entering the loop, and clear it out after the
                    470: loop has exited.
                    471:
                    472: You don't need to be concerned about allocating additional space for MP
                    473: variables.  All functions in MP automatically allocate additional space when a
                    474: variable does not already have enough space.  They do not, however, reduce the
                    475: space when a smaller number is stored in the object.  Most of the time, this
                    476: policy is best, since it avoids frequent re-allocation.
                    477:
                    478:
                    479: @section Useful Macros and Constants
                    480:
                    481: @deftypevr {Global Constant} {const int} mp_bits_per_limb
                    482: The number of bits per limb.
                    483: @end deftypevr
                    484:
                    485: @defmac __GNU_MP_VERSION
                    486: @defmacx __GNU_MP_VERSION_MINOR
                    487: The major and minor MP version, respectively, as integers.
                    488: @end defmac
                    489:
                    490: @section Compatibility with Version 1.x
                    491:
                    492: This version of MP is upward compatible with previous versions of MP, with a
                    493: few exceptions.
                    494:
                    495: @enumerate
                    496: @item Integer division functions round the result differently.  The old
                    497: functions (@code{mpz_div}, @code{mpz_divmod}, @code{mpz_mdiv},
                    498: @code{mpz_mdivmod}, etc) now all use floor rounding (i.e., they round the
                    499: quotient to @minus{}infinity).  There are a lot of new functions for integer
                    500: division, giving the user better control over the rounding.
                    501:
                    502: @item The function @code{mpz_mod} now compute the true @strong{mod} function.
                    503:
                    504: @item The functions @code{mpz_powm} and @code{mpz_powm_ui} now use
                    505: @strong{mod} for reduction.
                    506:
                    507: @item The assignment functions for rational numbers do no longer canonicalize
                    508: their results.  In the case a non-canonical result could arise from an
                    509: assignment, the user need to insert an explicit call to
                    510: @code{mpq_canonicalize}.  This change was made for efficiency.
                    511:
                    512: @item Output generated by @code{mpz_out_raw} in this release cannot be read
                    513: by @code{mpz_inp_raw} in previous releases.  This change was made for making
                    514: the file format truly portable between machines with different word sizes.
                    515:
                    516: @item Several @code{mpn} functions have changed.  But they were intentionally
                    517: undocumented in previous releases.
                    518:
                    519: @item The functions @code{mpz_cmp_ui}, @code{mpz_cmp_si}, and @code{mpq_cmp_ui}
                    520: are now implementated as macros, and thereby sometimes evaluate their
                    521: arguments multiple times.
                    522:
                    523: @item The functions @code{mpz_pow_ui} and @code{mpz_ui_pow_ui} now yield 1
                    524: for 0^0.  (In version 1, they yielded 0.)
                    525:
                    526: @end enumerate
                    527:
                    528:
                    529: @section Getting the Latest Version of MP
                    530:
                    531: The latest version of the MP library is available by anonymous ftp from
                    532: from @samp{prep.ai.mit.edu}.  The file name is
                    533: @file{/pub/gnu/gmp-M.N.tar.gz}.  Many sites around the world mirror
                    534: @samp{prep}; please use a mirror site near you.
                    535:
                    536: @node Reporting Bugs, Integer Functions, MP Basics, Top
                    537: @comment  node-name,  next,  previous,  up
                    538: @chapter Reporting Bugs
                    539: @cindex Reporting bugs
                    540:
                    541: If you think you have found a bug in the MP library, please investigate it and
                    542: report it.  We have made this library available to you, and it is not to ask
                    543: too much from you, to ask you to report the bugs that you find.
                    544:
                    545: There are a few things you should think about when you put your bug report
                    546: together.
                    547:
                    548: You have to send us a test case that makes it possible for us to reproduce the
                    549: bug.  Include instructions on how to run the test case.
                    550:
                    551: You also have to explain what is wrong; if you get a crash, or if the results
                    552: printed are incorrect and in that case, in what way.
                    553:
                    554: It is not uncommon that an observed problem is actually due to a bug in the
                    555: compiler used when building MP; the MP code tends to explore interesting
                    556: corners in compilers.  Therefore, please include compiler version information
                    557: in your bug report.  This can be extracted using @samp{what `which cc`}, or,
                    558: if you're using gcc, @samp{gcc -v}.  Also, include the output from @samp{uname
                    559: -a}.
                    560:
                    561: If your bug report is good, we will do our best to help you to get a corrected
                    562: version of the library; if the bug report is poor, we won't do anything about
                    563: it (aside of chiding you to send better bug reports).
                    564:
                    565: Send your bug report to: @samp{bug-gmp@@prep.ai.mit.edu}.
                    566:
                    567: If you think something in this manual is unclear, or downright incorrect, or if
                    568: the language needs to be improved, please send a note to the same address.
                    569:
                    570:
                    571: @node Integer Functions, Rational Number Functions, Reporting Bugs, Top
                    572: @comment  node-name,  next,  previous,  up
                    573: @chapter Integer Functions
                    574: @cindex Integer functions
                    575:
                    576: This chapter describes the MP functions for performing integer arithmetic.
                    577: These functions start with the prefix @code{mpz_}.
                    578:
                    579: Arbitrary precision integers are stored in objects of type @code{mpz_t}.
                    580:
                    581: @menu
                    582: * Initializing Integers::
                    583: * Assigning Integers::
                    584: * Simultaneous Integer Init & Assign::
                    585: * Converting Integers::
                    586: * Integer Arithmetic::
                    587: * Comparison Functions::
                    588: * Integer Logic and Bit Fiddling::
                    589: * I/O of Integers::
                    590: * Miscellaneous Integer Functions::
                    591: @end menu
                    592:
                    593: @node Initializing Integers, Assigning Integers, , Integer Functions
                    594: @comment  node-name,  next,  previous,  up
                    595: @section Initialization and Assignment Functions
                    596:
                    597: The functions for integer arithmetic assume that all integer objects are
                    598: initialized.  You do that by calling the function @code{mpz_init}.
                    599:
                    600: @deftypefun void mpz_init (mpz_t @var{integer})
                    601: Initialize @var{integer} with limb space and set the initial numeric value to
                    602: 0.  Each variable should normally only be initialized once, or at least cleared
                    603: out (using @code{mpz_clear}) between each initialization.
                    604: @end deftypefun
                    605:
                    606: Here is an example of using @code{mpz_init}:
                    607:
                    608: @example
                    609: @{
                    610:   mpz_t integ;
                    611:   mpz_init (integ);
                    612:   @dots{}
                    613:   mpz_add (integ, @dots{});
                    614:   @dots{}
                    615:   mpz_sub (integ, @dots{});
                    616:
                    617:   /* Unless the program is about to exit, do ... */
                    618:   mpz_clear (integ);
                    619: @}
                    620: @end example
                    621:
                    622: @noindent
                    623: As you can see, you can store new values any number of times, once an
                    624: object is initialized.
                    625:
                    626: @deftypefun void mpz_clear (mpz_t @var{integer})
                    627: Free the limb space occupied by @var{integer}.  Make sure to call this
                    628: function for all @code{mpz_t} variables when you are done with them.
                    629: @end deftypefun
                    630:
                    631: @deftypefun {void *} _mpz_realloc (mpz_t @var{integer}, mp_size_t @var{new_alloc})
                    632: Change the limb space allocation to @var{new_alloc} limbs.  This function is
                    633: not normally called from user code, but it can be used to give memory back to
                    634: the heap, or to increase the space of a variable to avoid repeated automatic
                    635: re-allocation.
                    636: @end deftypefun
                    637:
                    638: @deftypefun void mpz_array_init (mpz_t @var{integer_array}[], size_t @var{array_size}, mp_size_t @var{fixed_num_bits})
                    639: Allocate @strong{fixed} limb space for all @var{array_size} integers in
                    640: @var{integer_array}.  The fixed allocation for each integer in the array is
                    641: enough to store @var{fixed_num_bits}.  If the fixed space will be insufficient
                    642: for storing the result of a subsequent calculation, the result is
                    643: unpredictable.
                    644:
                    645: This function is useful for decreasing the working set for some algorithms
                    646: that use large integer arrays.
                    647:
                    648: There is no way to de-allocate the storage allocated by this function.
                    649: Don't call @code{mpz_clear}!
                    650: @end deftypefun
                    651:
                    652:
                    653: @node Assigning Integers, Simultaneous Integer Init & Assign, Initializing Integers, Integer Functions
                    654: @comment  node-name,  next,  previous,  up
                    655: @subsection Assignment Functions
                    656: @cindex Integer assignment functions
                    657:
                    658: These functions assign new values to already initialized integers
                    659: (@pxref{Initializing Integers}).
                    660:
                    661: @deftypefun void mpz_set (mpz_t @var{rop}, mpz_t @var{op})
                    662: @deftypefunx void mpz_set_ui (mpz_t @var{rop}, unsigned long int @var{op})
                    663: @deftypefunx void mpz_set_si (mpz_t @var{rop}, signed long int @var{op})
                    664: @deftypefunx void mpz_set_d (mpz_t @var{rop}, double @var{op})
                    665: @deftypefunx void mpz_set_q (mpz_t @var{rop}, mpq_t @var{op})
                    666: @deftypefunx void mpz_set_f (mpz_t @var{rop}, mpf_t @var{op})
                    667: Set the value of @var{rop} from @var{op}.
                    668: @end deftypefun
                    669:
                    670: @deftypefun int mpz_set_str (mpz_t @var{rop}, char *@var{str}, int @var{base})
                    671: Set the value of @var{rop} from @var{str}, a '\0'-terminated C string in base
                    672: @var{base}.  White space is allowed in the string, and is simply ignored.  The
                    673: base may vary from 2 to 36.  If @var{base} is 0, the actual base is determined
                    674: from the leading characters: if the first two characters are `0x' or `0X',
                    675: hexadecimal is assumed, otherwise if the first character is `0', octal is
                    676: assumed, otherwise decimal is assumed.
                    677:
                    678: This function returns 0 if the entire string up to the '\0' is a valid
                    679: number in base @var{base}.  Otherwise it returns @minus{}1.
                    680: @end deftypefun
                    681:
                    682:
                    683: @node Simultaneous Integer Init & Assign, Converting Integers, Assigning Integers, Integer Functions
                    684: @comment  node-name,  next,  previous,  up
                    685: @subsection Combined Initialization and Assignment Functions
                    686: @cindex Initialization and assignment functions
                    687:
                    688: For convenience, MP provides a parallel series of initialize-and-set functions
                    689: which initialize the output and then store the value there.  These functions'
                    690: names have the form @code{mpz_init_set@dots{}}
                    691:
                    692: Here is an example of using one:
                    693:
                    694: @example
                    695: @{
                    696:   mpz_t pie;
                    697:   mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10);
                    698:   @dots{}
                    699:   mpz_sub (pie, @dots{});
                    700:   @dots{}
                    701:   mpz_clear (pie);
                    702: @}
                    703: @end example
                    704:
                    705: @noindent
                    706: Once the integer has been initialized by any of the @code{mpz_init_set@dots{}}
                    707: functions, it can be used as the source or destination operand for the ordinary
                    708: integer functions.  Don't use an initialize-and-set function on a variable
                    709: already initialized!
                    710:
                    711: @deftypefun void mpz_init_set (mpz_t @var{rop}, mpz_t @var{op})
                    712: @deftypefunx void mpz_init_set_ui (mpz_t @var{rop}, unsigned long int @var{op})
                    713: @deftypefunx void mpz_init_set_si (mpz_t @var{rop}, signed long int @var{op})
                    714: @deftypefunx void mpz_init_set_d (mpz_t @var{rop}, double @var{op})
                    715: Initialize @var{rop} with limb space and set the initial numeric value from
                    716: @var{op}.
                    717: @end deftypefun
                    718:
                    719: @deftypefun int mpz_init_set_str (mpz_t @var{rop}, char *@var{str}, int @var{base})
                    720: Initialize @var{rop} and set its value like @code{mpz_set_str} (see its
                    721: documentation above for details).
                    722:
                    723: If the string is a correct base @var{base} number, the function returns 0;
                    724: if an error occurs it returns @minus{}1.  @var{rop} is initialized even if
                    725: an error occurs.  (I.e., you have to call @code{mpz_clear} for it.)
                    726: @end deftypefun
                    727:
                    728:
                    729: @node Converting Integers,  Integer Arithmetic, Simultaneous Integer Init & Assign, Integer Functions
                    730: @comment  node-name,  next,  previous,  up
                    731: @section Conversion Functions
                    732: @cindex Integer conversion functions
                    733: @cindex Conversion functions
                    734:
                    735: This section describes functions for converting arbitrary precision integers
                    736: to standard C types.  Functions for converting @emph{to} arbitrary
                    737: precision integers are described in @ref{Assigning Integers} and @ref{I/O of
                    738: Integers}.
                    739:
                    740: @deftypefun {unsigned long int} mpz_get_ui (mpz_t @var{op})
                    741: Return the least significant part from @var{op}.  This function combined
                    742: with @* @code{mpz_tdiv_q_2exp(@dots{}, @var{op}, CHAR_BIT*sizeof(unsigned
                    743: long int))} can be used to extract the limbs of an integer.
                    744: @end deftypefun
                    745:
                    746: @deftypefun {signed long int} mpz_get_si (mpz_t @var{op})
                    747: If @var{op} fits into a @code{signed long int} return the value of @var{op}.
                    748: Otherwise return the least significant part of @var{op}, with the same sign
                    749: as @var{op}.
                    750:
                    751: If @var{op} is too large to fit in a @code{signed long int}, the returned
                    752: result is probably not very useful.  @c To find out if the value will fit, use
                    753: @c the function @code{mpz_fits_si}.
                    754: @end deftypefun
                    755:
                    756: @deftypefun double mpz_get_d (mpz_t @var{op})
                    757: Convert @var{op} to a double.
                    758: @end deftypefun
                    759:
                    760: @deftypefun {char *} mpz_get_str (char *@var{str}, int @var{base}, mpz_t @var{op})
                    761: Convert @var{op} to a string of digits in base @var{base}.  The base may vary
                    762: from 2 to 36.
                    763:
                    764: If @var{str} is NULL, space for the result string is allocated using the
                    765: default allocation function, and a pointer to the string is returned.
                    766:
                    767: If @var{str} is not NULL, it should point to a block of storage enough large
                    768: for the result.  To find out the right amount of space to provide for
                    769: @var{str}, use @code{mpz_sizeinbase (@var{op}, @var{base}) + 2}.  The two
                    770: extra bytes are for a possible minus sign, and for the terminating null
                    771: character.
                    772: @end deftypefun
                    773:
                    774:
                    775: @node Integer Arithmetic, Comparison Functions, Converting Integers, Integer Functions
                    776: @comment  node-name,  next,  previous,  up
                    777: @section Arithmetic Functions
                    778: @cindex Integer arithmetic functions
                    779: @cindex Arithmetic functions
                    780:
                    781: @deftypefun void mpz_add (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                    782: @deftypefunx void mpz_add_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                    783: @ifinfo
                    784: Set @var{rop} to @var{op1} + @var{op2}.
                    785: @end ifinfo
                    786: @iftex
                    787: @tex
                    788: Set @var{rop} to $@var{op1} + @var{op2}$.
                    789: @end tex
                    790: @end iftex
                    791: @end deftypefun
                    792:
                    793: @deftypefun void mpz_sub (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                    794: @deftypefunx void mpz_sub_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                    795: Set @var{rop} to @var{op1} @minus{} @var{op2}.
                    796: @end deftypefun
                    797:
                    798: @deftypefun void mpz_mul (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                    799: @deftypefunx void mpz_mul_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                    800: @ifinfo
                    801: Set @var{rop} to @var{op1} times @var{op2}.
                    802: @end ifinfo
                    803: @iftex
                    804: @tex
                    805: Set @var{rop} to $@var{op1} \times @var{op2}$.
                    806: @end tex
                    807: @end iftex
                    808: @end deftypefun
                    809:
                    810: @deftypefun void mpz_mul_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                    811: @ifinfo
                    812: Set @var{rop} to @var{op1} times 2 raised to @var{op2}.  This operation can
                    813: also be defined as a left shift, @var{op2} steps.
                    814: @end ifinfo
                    815: @iftex
                    816: @tex
                    817: Set @var{rop} to $@var{op1} \times 2^{op2}$.  This operation can also be
                    818: defined as a left shift, @var{op2} steps.
                    819: @end tex
                    820: @end iftex
                    821: @end deftypefun
                    822:
                    823: @deftypefun void mpz_neg (mpz_t @var{rop}, mpz_t @var{op})
                    824: Set @var{rop} to @minus{}@var{op}.
                    825: @end deftypefun
                    826:
                    827: @deftypefun void mpz_abs (mpz_t @var{rop}, mpz_t @var{op})
                    828: Set @var{rop} to the absolute value of @var{op}.
                    829: @end deftypefun
                    830:
                    831: @deftypefun void mpz_fac_ui (mpz_t @var{rop}, unsigned long int @var{op})
                    832: Set @var{rop} to @var{op}!, the factorial of @var{op}.
                    833: @end deftypefun
                    834:
                    835: @subsection Division functions
                    836:
                    837: Division is undefined if the divisor is zero, and passing a zero divisor to
                    838: the divide or modulo functions, as well passing a zero mod argument to the
                    839: @code{mpz_powm} and @code{mpz_powm_ui} functions, will make these functions
                    840: intentionally divide by zero.  This gives the user the possibility to handle
                    841: arithmetic exceptions in these functions in the same manner as other
                    842: arithmetic exceptions.
                    843:
                    844: There are three main groups of division functions:
                    845: @itemize @bullet
                    846: @item
                    847: Functions that truncate the quotient towards 0.  The names of these
                    848: functions start with @code{mpz_tdiv}.  The @samp{t} in the name is short for
                    849: @samp{truncate}.
                    850: @item
                    851: Functions that round the quotient towards @minus{}infinity.  The names of
                    852: these routines start with @code{mpz_fdiv}.  The @samp{f} in the name is
                    853: short for @samp{floor}.
                    854: @item
                    855: Functions that round the quotient towards +infinity.  The names of
                    856: these routines start with @code{mpz_cdiv}.  The @samp{c} in the name is
                    857: short for @samp{ceil}.
                    858: @end itemize
                    859:
                    860: For each rounding mode, there are a couple of variants.  Here @samp{q} means
                    861: that the quotient is computed, while @samp{r} means that the remainder is
                    862: computed.  Functions that compute both the quotient and remainder have
                    863: @samp{qr} in the name.
                    864:
                    865: @deftypefun void mpz_tdiv_q (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                    866: @deftypefunx void mpz_tdiv_q_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                    867: Set @var{rop} to [@var{op1}/@var{op2}].  The quotient is truncated towards
                    868: 0.
                    869: @end deftypefun
                    870:
                    871: @deftypefun void mpz_tdiv_r (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                    872: @deftypefunx void mpz_tdiv_r_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                    873: Set @var{rop} to (@var{op1} - [@var{op1}/@var{op2}] * @var{op2}).
                    874: Unless the remainder is zero, it has the same sign as the dividend.
                    875: @end deftypefun
                    876:
                    877: @deftypefun void mpz_tdiv_qr (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, mpz_t @var{op2})
                    878: @deftypefunx void mpz_tdiv_qr_ui (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, unsigned long int @var{op2})
                    879: Divide @var{op1} by @var{op2} and put the quotient in @var{rop1} and the
                    880: remainder in @var{rop2}.  The quotient is rounded towards 0.  Unless the
                    881: remainder is zero, it has the same sign as the dividend.
                    882:
                    883: If @var{rop1} and @var{rop2} are the same variable, the results are
                    884: undefined.
                    885: @end deftypefun
                    886:
                    887: @deftypefun void mpz_fdiv_q (mpz_t @var{rop1}, mpz_t @var{op1}, mpz_t @var{op2})
                    888: @deftypefunx void mpz_fdiv_q_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                    889: @ifinfo
                    890: Set @var{rop} to @var{op1}/@var{op2}.  The quotient is rounded towards
                    891: @minus{}infinity.
                    892: @end ifinfo
                    893: @iftex
                    894: @tex
                    895: Set @var{rop} to $\lfloor@var{op1}/@var{op2}\rfloor$.  (I.e., round
                    896: the quotient towards $-\infty$.)
                    897: @end tex
                    898: @end iftex
                    899: @end deftypefun
                    900:
                    901: @deftypefun void mpz_fdiv_r (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                    902: @deftypefunx {unsigned long int} mpz_fdiv_r_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                    903: Divide @var{op1} by @var{op2} and put the remainder in @var{rop}.  Unless
                    904: the remainder is zero, it has the same sign as the divisor.
                    905:
                    906: For @code{mpz_fdiv_r_ui} the remainder is small enough to fit in an
                    907: @code{unsigned long int}, and is therefore returned.
                    908: @end deftypefun
                    909:
                    910: @deftypefun void mpz_fdiv_qr (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, mpz_t @var{op2})
                    911: @deftypefunx {unsigned long int} mpz_fdiv_qr_ui (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, unsigned long int @var{op2})
                    912: Divide @var{op1} by @var{op2} and put the quotient in @var{rop1} and the
                    913: remainder in @var{rop2}.  The quotient is rounded towards @minus{}infinity.
                    914: Unless the remainder is zero, it has the same sign as the divisor.
                    915:
                    916: For @code{mpz_fdiv_qr_ui} the remainder is small enough to fit in an
                    917: @code{unsigned long int}, and is therefore returned.
                    918:
                    919: If @var{rop1} and @var{rop2} are the same variable, the results are
                    920: undefined.
                    921: @end deftypefun
                    922:
                    923: @deftypefun {unsigned long int} mpz_fdiv_ui (mpz_t @var{op1}, unsigned long int @var{op2})
                    924: This function is similar to @code{mpz_fdiv_r_ui}, but the remainder is only
                    925: returned; it is not stored anywhere.
                    926: @end deftypefun
                    927:
                    928: @deftypefun void mpz_cdiv_q (mpz_t @var{rop1}, mpz_t @var{op1}, mpz_t @var{op2})
                    929: @deftypefunx void mpz_cdiv_q_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                    930: @ifinfo
                    931: Set @var{rop} to @var{op1}/@var{op2}.  The quotient is rounded towards
                    932: +infinity.
                    933: @end ifinfo
                    934: @iftex
                    935: @tex
                    936: Set @var{rop} to $\lceil@var{op1}/@var{op2}\rceil$.  (I.e., round the
                    937: quotient towards $+\infty$.)
                    938: @end tex
                    939: @end iftex
                    940: @end deftypefun
                    941:
                    942: @deftypefun void mpz_cdiv_r (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                    943: @deftypefunx {unsigned long int} mpz_cdiv_r_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                    944: Divide @var{op1} by @var{op2} and put the remainder in @var{rop}.  Unless
                    945: the remainder is zero, it has the opposite sign as the divisor.
                    946:
                    947: For @code{mpz_cdiv_r_ui} the negated remainder is small enough to fit in an
                    948: @code{unsigned long int}, and it is therefore returned.
                    949: @end deftypefun
                    950:
                    951: @deftypefun void mpz_cdiv_qr (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, mpz_t @var{op2})
                    952: @deftypefunx {unsigned long int} mpz_cdiv_qr_ui (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, unsigned long int @var{op2})
                    953: Divide @var{op1} by @var{op2} and put the quotient in @var{rop1} and the
                    954: remainder in @var{rop2}.  The quotient is rounded towards +infinity.  Unless
                    955: the remainder is zero, it has the opposite sign as the divisor.
                    956:
                    957: For @code{mpz_cdiv_qr_ui} the negated remainder is small enough to fit in an
                    958: @code{unsigned long int}, and it is therefore returned.
                    959:
                    960: If @var{rop1} and @var{rop2} are the same variable, the results are
                    961: undefined.
                    962: @end deftypefun
                    963:
                    964: @deftypefun {unsigned long int} mpz_cdiv_ui (mpz_t @var{op1}, unsigned long int @var{op2})
                    965: Return the negated remainder, similar to @code{mpz_cdiv_r_ui}.  (The
                    966: difference is that this function doesn't store the remainder anywhere.)
                    967: @end deftypefun
                    968:
                    969: @deftypefun void mpz_mod (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                    970: @deftypefunx {unsigned long int} mpz_mod_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                    971: Set @var{rop} to @var{op1} @code{mod} @var{op2}.  The sign of the divisor is
                    972: ignored, and the result is always non-negative.
                    973:
                    974: For @code{mpz_mod_ui} the remainder is small enough to fit in an
                    975: @code{unsigned long int}, and is therefore returned.
                    976: @end deftypefun
                    977:
                    978: @deftypefun void mpz_divexact (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                    979: Set @var{rop} to @var{op1}/@var{op2}.  This function produces correct
                    980: results only when it is known in advance that @var{op2} divides
                    981: @var{op1}.
                    982:
                    983: Since mpz_divexact is much faster than any of the other routines that produce
                    984: the quotient (@pxref{References} Jebelean), it is the best choice for
                    985: instances in which exact division is known to occur, such as reducing a
                    986: rational to lowest terms.
                    987: @end deftypefun
                    988:
                    989: @deftypefun void mpz_tdiv_q_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                    990: @ifinfo
                    991: Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}.  The quotient is
                    992: rounded towards 0.
                    993: @end ifinfo
                    994: @iftex
                    995: @tex
                    996: Set @var{rop} to $@var{op1}/2^{op2}$.  The quotient is rounded towards 0.
                    997: @end tex
                    998: @end iftex
                    999: @end deftypefun
                   1000:
                   1001: @deftypefun void mpz_tdiv_r_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                   1002: @ifinfo
                   1003: Divide @var{op1} by (2 raised to @var{op2}) and put the remainder in
                   1004: @var{rop}.  Unless it is zero, @var{rop} will have the same sign as @var{op1}.
                   1005: @end ifinfo
                   1006: @iftex
                   1007: @tex
                   1008: Divide @var{op1} by $2^{op2}$ and put the remainder in @var{rop}.  Unless it is
                   1009: zero, @var{rop} will have the same sign as @var{op1}.
                   1010: @end tex
                   1011: @end iftex
                   1012: @end deftypefun
                   1013:
                   1014: @deftypefun void mpz_fdiv_q_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                   1015: @ifinfo
                   1016: Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}.  The quotient is
                   1017: rounded towards @minus{}infinity.
                   1018: @end ifinfo
                   1019: @iftex
                   1020: @tex
                   1021: Set @var{rop} to $\lfloor@var{op1}/2^{op2}\rfloor$.  The quotient is rounded
                   1022: towards $-\infty$.
                   1023: @end tex
                   1024: @end iftex
                   1025: @end deftypefun
                   1026:
                   1027: @deftypefun void mpz_fdiv_r_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                   1028: @ifinfo
                   1029: Divide @var{op1} by (2 raised to @var{op2}) and put the remainder in
                   1030: @var{rop}.  The sign of @var{rop} will always be positive.
                   1031: @end ifinfo
                   1032: @iftex
                   1033: @tex
                   1034: Divide @var{op1} by $2^{op2}$ and put the remainder in @var{rop}.  The sign of
                   1035: @var{rop} will always be positive.
                   1036: @end tex
                   1037: @end iftex
                   1038:
                   1039: This operation can also be defined as masking of the @var{op2} least
                   1040: significant bits.
                   1041: @end deftypefun
                   1042:
                   1043: @subsection Exponentialization Functions
                   1044:
                   1045: @deftypefun void mpz_powm (mpz_t @var{rop}, mpz_t @var{base}, mpz_t @var{exp}, mpz_t @var{mod})
                   1046: @deftypefunx void mpz_powm_ui (mpz_t @var{rop}, mpz_t @var{base}, unsigned long int @var{exp}, mpz_t @var{mod})
                   1047: Set @var{rop} to (@var{base} raised to @var{exp}) @code{mod} @var{mod}.  If
                   1048: @var{exp} is negative, the result is undefined.
                   1049: @end deftypefun
                   1050:
                   1051: @deftypefun void mpz_pow_ui (mpz_t @var{rop}, mpz_t @var{base}, unsigned long int @var{exp})
                   1052: @deftypefunx void mpz_ui_pow_ui (mpz_t @var{rop}, unsigned long int @var{base}, unsigned long int @var{exp})
                   1053: Set @var{rop} to @var{base} raised to @var{exp}.
                   1054: @ifinfo
                   1055: The case of 0^0 yields 1.
                   1056: @end ifinfo
                   1057: @iftex
                   1058: @tex
                   1059: The case of $0^0$ yields 1.
                   1060: @end tex
                   1061: @end iftex
                   1062: @end deftypefun
                   1063:
                   1064: @subsection Square Root Functions
                   1065:
                   1066: @deftypefun void mpz_sqrt (mpz_t @var{rop}, mpz_t @var{op})
                   1067: @ifinfo
                   1068: Set @var{rop} to the truncated integer part of the square root of
                   1069: @var{op}.
                   1070: @end ifinfo
                   1071: @iftex
                   1072: @tex
                   1073: Set @var{rop} to $\lfloor\sqrt{@var{op}}\rfloor$, the truncated integer
                   1074: part of the square root of @var{op}.
                   1075: @end tex
                   1076: @end iftex
                   1077: @end deftypefun
                   1078:
                   1079: @deftypefun void mpz_sqrtrem (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op})
                   1080: @ifinfo
                   1081: Set @var{rop1} to the truncated integer part of the square root of @var{op},
                   1082: like @code{mpz_sqrt}.  Set @var{rop2} to
                   1083: @var{op}@minus{}@var{rop1}*@var{rop1},
                   1084: @end ifinfo
                   1085: @iftex
                   1086: @tex
                   1087: Set @var{rop1} to $\lfloor\sqrt{@var{op}}\rfloor$, like @code{mpz_sqrt}.
                   1088: Set @var{rop2} to $(@var{op} - @var{rop1}^2)$,
                   1089: @end tex
                   1090: @end iftex
                   1091: (i.e., zero if @var{op} is a perfect square).
                   1092:
                   1093: If @var{rop1} and @var{rop2} are the same variable, the results are
                   1094: undefined.
                   1095: @end deftypefun
                   1096:
                   1097: @deftypefun int mpz_perfect_square_p (mpz_t @var{op})
                   1098: Return non-zero if @var{op} is a perfect square, i.e., if the square root of
                   1099: @var{op} is an integer.  Return zero otherwise.
                   1100: @end deftypefun
                   1101:
                   1102: @subsection Number Theoretic Functions
                   1103:
                   1104: @deftypefun int mpz_probab_prime_p (mpz_t @var{op}, int @var{reps})
                   1105: @ifinfo
                   1106: If this function returns 0, @var{op} is definitely not prime.  If it returns
                   1107: 1, then @var{op} is `probably' prime.  The probability of a false positive is
                   1108: (1/4)**@var{reps}.
                   1109: @end ifinfo
                   1110: @iftex
                   1111: @tex
                   1112: If this function returns 0, @var{op} is definitely not prime.  If it returns
                   1113: 1, then @var{op} is `probably' prime.  The probability of a false positive is
                   1114: $(1/4)^{{reps}}$.
                   1115: @end tex
                   1116: @end iftex
                   1117: A reasonable value of reps is 25.
                   1118:
                   1119: An implementation of the probabilistic primality test found in Seminumerical
                   1120: Algorithms (@pxref{References} Knuth).
                   1121: @end deftypefun
                   1122:
                   1123: @deftypefun void mpz_gcd (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                   1124: Set @var{rop} to the greatest common divisor of @var{op1} and @var{op2}.
                   1125: @end deftypefun
                   1126:
                   1127: @deftypefun {unsigned long int} mpz_gcd_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2})
                   1128: Compute the greatest common divisor of @var{op1} and @var{op2}.  If
                   1129: @var{rop} is not NULL, store the result there.
                   1130:
                   1131: If the result is small enough to fit in an @code{unsigned long int}, it is
                   1132: returned.  If the result does not fit, 0 is returned, and the result is equal
                   1133: to the argument @var{op1}.  Note that the result will always fit if @var{op2}
                   1134: is non-zero.
                   1135: @end deftypefun
                   1136:
                   1137: @deftypefun void mpz_gcdext (mpz_t @var{g}, mpz_t @var{s}, mpz_t @var{t}, mpz_t @var{a}, mpz_t @var{b})
                   1138: Compute @var{g}, @var{s}, and @var{t}, such that @var{a}@var{s} +
                   1139: @var{b}@var{t} = @var{g} = @code{gcd} (@var{a}, @var{b}).  If @var{t} is
                   1140: NULL, that argument is not computed.
                   1141: @end deftypefun
                   1142:
                   1143: @deftypefun int mpz_invert (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                   1144: Compute the inverse of @var{op1} modulo @var{op2} and put the result in
                   1145: @var{rop}.  Return non-zero if an inverse exist, zero otherwise.  When the
                   1146: function returns zero, do not assume anything about the value in @var{rop}.
                   1147: @end deftypefun
                   1148:
                   1149: @deftypefun int mpz_jacobi (mpz_t @var{op1}, mpz_t @var{op2})
                   1150: @deftypefunx int mpz_legendre (mpz_t @var{op1}, mpz_t @var{op2})
                   1151: Compute the Jacobi and Legendre symbols, respectively.
                   1152: @end deftypefun
                   1153:
                   1154: @need 2000
                   1155: @node Comparison Functions, Integer Logic and Bit Fiddling, Integer Arithmetic, Integer Functions
                   1156: @comment  node-name,  next,  previous,  up
                   1157: @section Comparison Functions
                   1158:
                   1159: @deftypefun int mpz_cmp (mpz_t @var{op1}, mpz_t @var{op2})
                   1160: @ifinfo
                   1161: Compare @var{op1} and @var{op2}.  Return a positive value if @var{op1} >
                   1162: @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
                   1163: @var{op2}.
                   1164: @end ifinfo
                   1165: @iftex
                   1166: @tex
                   1167: Compare @var{op1} and @var{op2}.  Return a positive value if $@var{op1} >
                   1168: @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
                   1169: < @var{op2}$.
                   1170: @end tex
                   1171: @end iftex
                   1172: @end deftypefun
                   1173:
                   1174: @deftypefn Macro int mpz_cmp_ui (mpz_t @var{op1}, unsigned long int @var{op2})
                   1175: @deftypefnx Macro int mpz_cmp_si (mpz_t @var{op1}, signed long int @var{op2})
                   1176: @ifinfo
                   1177: Compare @var{op1} and @var{op2}.  Return a positive value if @var{op1} >
                   1178: @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
                   1179: @var{op2}.
                   1180: @end ifinfo
                   1181: @iftex
                   1182: @tex
                   1183: Compare @var{op1} and @var{op2}.  Return a positive value if $@var{op1} >
                   1184: @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
                   1185: < @var{op2}$.
                   1186: @end tex
                   1187: @end iftex
                   1188:
                   1189: These functions are actually implemented as macros.  They evaluate their
                   1190: arguments multiple times.
                   1191: @end deftypefn
                   1192:
                   1193: @deftypefn Macro int mpz_sgn (mpz_t @var{op})
                   1194: @ifinfo
                   1195: Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0.
                   1196: @end ifinfo
                   1197: @iftex
                   1198: @tex
                   1199: Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$.
                   1200: @end tex
                   1201: @end iftex
                   1202:
                   1203: This function is actually implemented as a macro.  It evaluates its
                   1204: arguments multiple times.
                   1205: @end deftypefn
                   1206:
                   1207: @node Integer Logic and Bit Fiddling, I/O of Integers, Comparison Functions, Integer Functions
                   1208: @comment  node-name,  next,  previous,  up
                   1209: @section Logical and Bit Manipulation Functions
                   1210: @cindex Logical functions
                   1211: @cindex Bit manipulation functions
                   1212:
                   1213: These functions behave as if two's complement arithmetic were used (although
                   1214: sign-magnitude is used by the actual implementation).
                   1215:
                   1216: @deftypefun void mpz_and (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                   1217: Set @var{rop} to @var{op1} logical-and @var{op2}.
                   1218: @end deftypefun
                   1219:
                   1220: @deftypefun void mpz_ior (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                   1221: Set @var{rop} to @var{op1} inclusive-or @var{op2}.
                   1222: @end deftypefun
                   1223:
                   1224: @c @deftypefun void mpz_xor (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2})
                   1225: @c Set @var{rop} to @var{op1} exclusive-or @var{op2}.
                   1226: @c @end deftypefun
                   1227:
                   1228: @deftypefun void mpz_com (mpz_t @var{rop}, mpz_t @var{op})
                   1229: Set @var{rop} to the one's complement of @var{op}.
                   1230: @end deftypefun
                   1231:
                   1232: @deftypefun {unsigned long int} mpz_popcount (mpz_t @var{op})
                   1233: For non-negative numbers, return the population count of @var{op}.  For
                   1234: negative numbers, return the largest possible value (@var{MAX_ULONG}).
                   1235: @end deftypefun
                   1236:
                   1237: @deftypefun {unsigned long int} mpz_hamdist (mpz_t @var{op1}, mpz_t @var{op2})
                   1238: If @var{op1} and @var{op2} are both non-negative, return the hamming distance
                   1239: between the two operands.  Otherwise, return the largest possible value
                   1240: (@var{MAX_ULONG}).
                   1241:
                   1242: It is possible to extend this function to return a useful value when the
                   1243: operands are both negative, but the current implementation returns
                   1244: @var{MAX_ULONG} in this case.  @strong{Do not depend on this behavior, since
                   1245: it will change in future versions of the library.}
                   1246: @end deftypefun
                   1247:
                   1248: @deftypefun {unsigned long int} mpz_scan0 (mpz_t @var{op}, unsigned long int @var{starting_bit})
                   1249: Scan @var{op}, starting with bit @var{starting_bit}, towards more significant
                   1250: bits, until the first clear bit is found.  Return the index of the found bit.
                   1251: @end deftypefun
                   1252:
                   1253: @deftypefun {unsigned long int} mpz_scan1 (mpz_t @var{op}, unsigned long int @var{starting_bit})
                   1254: Scan @var{op}, starting with bit @var{starting_bit}, towards more significant
                   1255: bits, until the first set bit is found.  Return the index of the found bit.
                   1256: @end deftypefun
                   1257:
                   1258: @deftypefun void mpz_setbit (mpz_t @var{rop}, unsigned long int @var{bit_index})
                   1259: Set bit @var{bit_index} in @var{op1}.
                   1260: @end deftypefun
                   1261:
                   1262: @deftypefun void mpz_clrbit (mpz_t @var{rop}, unsigned long int @var{bit_index})
                   1263: Clear bit @var{bit_index} in @var{op1}.
                   1264: @end deftypefun
                   1265:
                   1266: @node I/O of Integers, Miscellaneous Integer Functions, Integer Logic and Bit Fiddling, Integer Functions
                   1267: @comment  node-name,  next,  previous,  up
                   1268: @section Input and Output Functions
                   1269: @cindex Integer input and output functions
                   1270: @cindex Input functions
                   1271: @cindex Output functions
                   1272: @cindex I/O functions
                   1273:
                   1274: Functions that perform input from a stdio stream, and functions that output to
                   1275: a stdio stream.  Passing a NULL pointer for a @var{stream} argument to any of
                   1276: these functions will make them read from @code{stdin} and write to
                   1277: @code{stdout}, respectively.
                   1278:
                   1279: When using any of these functions, it is a good idea to include @file{stdio.h}
                   1280: before @file{gmp.h}, since that will allow @file{gmp.h} to define prototypes
                   1281: for these functions.
                   1282:
                   1283: @deftypefun size_t mpz_out_str (FILE *@var{stream}, int @var{base}, mpz_t @var{op})
                   1284: Output @var{op} on stdio stream @var{stream}, as a string of digits in base
                   1285: @var{base}.  The base may vary from 2 to 36.
                   1286:
                   1287: Return the number of bytes written, or if an error occurred, return 0.
                   1288: @end deftypefun
                   1289:
                   1290: @deftypefun size_t mpz_inp_str (mpz_t @var{rop}, FILE *@var{stream}, int @var{base})
                   1291: Input a possibly white-space preceded string in base @var{base} from stdio
                   1292: stream @var{stream}, and put the read integer in @var{rop}.  The base may vary
                   1293: from 2 to 36.  If @var{base} is 0, the actual base is determined from the
                   1294: leading characters: if the first two characters are `0x' or `0X', hexadecimal
                   1295: is assumed, otherwise if the first character is `0', octal is assumed,
                   1296: otherwise decimal is assumed.
                   1297:
                   1298: Return the number of bytes read, or if an error occurred, return 0.
                   1299: @end deftypefun
                   1300:
                   1301: @deftypefun size_t mpz_out_raw (FILE *@var{stream}, mpz_t @var{op})
                   1302: Output @var{op} on stdio stream @var{stream}, in raw binary format.  The
                   1303: integer is written in a portable format, with 4 bytes of size information, and
                   1304: that many bytes of limbs.  Both the size and the limbs are written in
                   1305: decreasing significance order (i.e., in big-endian).
                   1306:
                   1307: The output can be read with @code{mpz_inp_raw}.
                   1308:
                   1309: Return the number of bytes written, or if an error occurred, return 0.
                   1310:
                   1311: The output of this can not be read by @code{mpz_inp_raw} from GMP 1, because
                   1312: of changes necessary for compatibility between 32-bit and 64-bit machines.
                   1313: @end deftypefun
                   1314:
                   1315: @deftypefun size_t mpz_inp_raw (mpz_t @var{rop}, FILE *@var{stream})
                   1316: Input from stdio stream @var{stream} in the format written by
                   1317: @code{mpz_out_raw}, and put the result in @var{rop}.  Return the number of
                   1318: bytes read, or if an error occurred, return 0.
                   1319:
                   1320: This routine can read the output from @code{mpz_out_raw} also from GMP 1, in
                   1321: spite of changes necessary for compatibility between 32-bit and 64-bit
                   1322: machines.
                   1323: @end deftypefun
                   1324:
                   1325:
                   1326: @need 2000
                   1327: @node Miscellaneous Integer Functions,, I/O of Integers, Integer Functions
                   1328: @comment  node-name,  next,  previous,  up
                   1329: @section Miscellaneous Functions
                   1330: @cindex Miscellaneous integer functions
                   1331:
                   1332: @deftypefun void mpz_random (mpz_t @var{rop}, mp_size_t @var{max_size})
                   1333: Generate a random integer of at most @var{max_size} limbs.  The generated
                   1334: random number doesn't satisfy any particular requirements of randomness.
                   1335: Negative random numbers are generated when @var{max_size} is negative.
                   1336: @end deftypefun
                   1337:
                   1338: @deftypefun void mpz_random2 (mpz_t @var{rop}, mp_size_t @var{max_size})
                   1339: Generate a random integer of at most @var{max_size} limbs, with long strings
                   1340: of zeros and ones in the binary representation.  Useful for testing functions
                   1341: and algorithms, since this kind of random numbers have proven to be more
                   1342: likely to trigger corner-case bugs.  Negative random numbers are generated
                   1343: when @var{max_size} is negative.
                   1344: @end deftypefun
                   1345:
                   1346: @deftypefun size_t mpz_size (mpz_t @var{op})
                   1347: Return the size of @var{op} measured in number of limbs.  If @var{op} is zero,
                   1348: the returned value will be zero.
                   1349: @c (@xref{Nomenclature}, for an explanation of the concept @dfn{limb}.)
                   1350:
                   1351: @strong{This function is obsolete.  It will disappear from future MP
                   1352: releases.}
                   1353: @end deftypefun
                   1354:
                   1355: @deftypefun size_t mpz_sizeinbase (mpz_t @var{op}, int @var{base})
                   1356: Return the size of @var{op} measured in number of digits in base @var{base}.
                   1357: The base may vary from 2 to 36.  The returned value will be exact or 1 too
                   1358: big.  If @var{base} is a power of 2, the returned value will always be exact.
                   1359:
                   1360: This function is useful in order to allocate the right amount of space before
                   1361: converting @var{op} to a string.  The right amount of allocation is normally
                   1362: two more than the value returned by @code{mpz_sizeinbase} (one extra for a
                   1363: minus sign and one for the terminating '\0').
                   1364: @end deftypefun
                   1365:
                   1366:
                   1367: @node Rational Number Functions, Floating-point Functions, Integer Functions, Top
                   1368: @comment  node-name,  next,  previous,  up
                   1369: @chapter Rational Number Functions
                   1370: @cindex Rational number functions
                   1371:
                   1372: This chapter describes the MP functions for performing arithmetic on rational
                   1373: numbers.  These functions start with the prefix @code{mpq_}.
                   1374:
                   1375: Rational numbers are stored in objects of type @code{mpq_t}.
                   1376:
                   1377: All rational arithmetic functions assume operands have a canonical form, and
                   1378: canonicalize their result.  The canonical from means that the denominator and
                   1379: the numerator have no common factors, and that the denominator is positive.
                   1380: Zero has the unique representation 0/1.
                   1381:
                   1382: Pure assignment functions do not canonicalize the assigned variable.  It is
                   1383: the responsibility of the user to canonicalize the assigned variable before
                   1384: any arithmetic operations are performed on that variable.  @strong{Note that
                   1385: this is an incompatible change from version 1 of the library.}
                   1386:
                   1387: @deftypefun void mpq_canonicalize (mpq_t @var{op})
                   1388: Remove any factors that are common to the numerator and denominator of
                   1389: @var{op}, and make the denominator positive.
                   1390: @end deftypefun
                   1391:
                   1392: @menu
                   1393: * Initializing Rationals::
                   1394: * Assigning Rationals::
                   1395: * Simultaneous Integer Init & Assign::
                   1396: * Comparing Rationals::
                   1397: * Applying Integer Functions::
                   1398: * Miscellaneous Rational Functions::
                   1399: @end menu
                   1400:
                   1401: @node Initializing Rationals, Assigning Rationals, Rational Number Functions, Rational Number Functions
                   1402: @comment  node-name,  next,  previous,  up
                   1403: @section Initialization and Assignment Functions
                   1404:
                   1405: @deftypefun void mpq_init (mpq_t @var{dest_rational})
                   1406: Initialize @var{dest_rational} and set it to 0/1.  Each variable should
                   1407: normally only be initialized once, or at least cleared out (using the function
                   1408: @code{mpq_clear}) between each initialization.
                   1409: @end deftypefun
                   1410:
                   1411: @deftypefun void mpq_clear (mpq_t @var{rational_number})
                   1412: Free the space occupied by @var{rational_number}.  Make sure to call this
                   1413: function for all @code{mpq_t} variables when you are done with them.
                   1414: @end deftypefun
                   1415:
                   1416: @deftypefun void mpq_set (mpq_t @var{rop}, mpq_t @var{op})
                   1417: @deftypefunx void mpq_set_z (mpq_t @var{rop}, mpz_t @var{op})
                   1418: Assign @var{rop} from @var{op}.
                   1419: @end deftypefun
                   1420:
                   1421: @deftypefun void mpq_set_ui (mpq_t @var{rop}, unsigned long int @var{op1}, unsigned long int @var{op2})
                   1422: @deftypefunx void mpq_set_si (mpq_t @var{rop}, signed long int @var{op1}, unsigned long int @var{op2})
                   1423: Set the value of @var{rop} to @var{op1}/@var{op2}.  Note that if @var{op1} and
                   1424: @var{op2} have common factors, @var{rop} has to be passed to
                   1425: @code{mpq_canonicalize} before any operations are performed on @var{rop}.
                   1426: @end deftypefun
                   1427:
                   1428: @node Assigning Rationals, Comparing Rationals, Initializing Rationals, Rational Number Functions
                   1429: @comment  node-name,  next,  previous,  up
                   1430: @section Arithmetic Functions
                   1431:
                   1432: @deftypefun void mpq_add (mpq_t @var{sum}, mpq_t @var{addend1}, mpq_t @var{addend2})
                   1433: Set @var{sum} to @var{addend1} + @var{addend2}.
                   1434: @end deftypefun
                   1435:
                   1436: @deftypefun void mpq_sub (mpq_t @var{difference}, mpq_t @var{minuend}, mpq_t @var{subtrahend})
                   1437: Set @var{difference} to @var{minuend} @minus{} @var{subtrahend}.
                   1438: @end deftypefun
                   1439:
                   1440: @deftypefun void mpq_mul (mpq_t @var{product}, mpq_t @var{multiplier}, mpq_t @var{multiplicand})
                   1441: @ifinfo
                   1442: Set @var{product} to @var{multiplier} times @var{multiplicand}.
                   1443: @end ifinfo
                   1444: @iftex
                   1445: @tex
                   1446: Set @var{product} to $@var{multiplier} \times @var{multiplicand}$.
                   1447: @end tex
                   1448: @end iftex
                   1449: @end deftypefun
                   1450:
                   1451: @deftypefun void mpq_div (mpq_t @var{quotient}, mpq_t @var{dividend}, mpq_t @var{divisor})
                   1452: Set @var{quotient} to @var{dividend}/@var{divisor}.
                   1453: @end deftypefun
                   1454:
                   1455: @deftypefun void mpq_neg (mpq_t @var{negated_operand}, mpq_t @var{operand})
                   1456: Set @var{negated_operand} to @minus{}@var{operand}.
                   1457: @end deftypefun
                   1458:
                   1459: @deftypefun void mpq_inv (mpq_t @var{inverted_number}, mpq_t @var{number})
                   1460: Set @var{inverted_number} to 1/@var{number}.  If the new denominator is
                   1461: zero, this routine will divide by zero.
                   1462: @end deftypefun
                   1463:
                   1464: @node Comparing Rationals, Applying Integer Functions, Assigning Rationals, Rational Number Functions
                   1465: @comment  node-name,  next,  previous,  up
                   1466: @section Comparison Functions
                   1467:
                   1468: @deftypefun int mpq_cmp (mpq_t @var{op1}, mpq_t @var{op2})
                   1469: @ifinfo
                   1470: Compare @var{op1} and @var{op2}.  Return a positive value if @var{op1} >
                   1471: @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
                   1472: @var{op2}.
                   1473: @end ifinfo
                   1474: @iftex
                   1475: @tex
                   1476: Compare @var{op1} and @var{op2}.  Return a positive value if $@var{op1} >
                   1477: @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
                   1478: < @var{op2}$.
                   1479: @end tex
                   1480: @end iftex
                   1481:
                   1482: To determine if two rationals are equal, @code{mpq_equal} is faster than
                   1483: @code{mpq_cmp}.
                   1484: @end deftypefun
                   1485:
                   1486: @deftypefn Macro int mpq_cmp_ui (mpq_t @var{op1}, unsigned long int @var{num2}, unsigned long int @var{den2})
                   1487: @ifinfo
                   1488: Compare @var{op1} and @var{num2}/@var{den2}.  Return a positive value if
                   1489: @var{op1} > @var{num2}/@var{den2}, zero if @var{op1} = @var{num2}/@var{den2},
                   1490: and a negative value if @var{op1} < @var{num2}/@var{den2}.
                   1491: @end ifinfo
                   1492: @iftex
                   1493: @tex
                   1494: Compare @var{op1} and @var{num2}/@var{den2}.  Return a positive value if
                   1495: $@var{op1} > @var{num2}/@var{den2}$, zero if $@var{op1} =
                   1496: @var{num2}/@var{den2}$, and a negative value if $@var{op1} <
                   1497: @var{num2}/@var{den2}$.
                   1498: @end tex
                   1499: @end iftex
                   1500:
                   1501: This routine allows that @var{num2} and @var{den2} have common factors.
                   1502:
                   1503: This function is actually implemented as a macro.  It evaluates its
                   1504: arguments multiple times.
                   1505: @end deftypefn
                   1506:
                   1507: @deftypefn Macro int mpq_sgn (mpq_t @var{op})
                   1508: @ifinfo
                   1509: Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0.
                   1510: @end ifinfo
                   1511: @iftex
                   1512: @tex
                   1513: Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$.
                   1514: @end tex
                   1515: @end iftex
                   1516:
                   1517: This function is actually implemented as a macro.  It evaluates its
                   1518: arguments multiple times.
                   1519: @end deftypefn
                   1520:
                   1521: @deftypefun int mpq_equal (mpq_t @var{op1}, mpq_t @var{op2})
                   1522: Return non-zero if @var{op1} and @var{op2} are equal, zero if they are
                   1523: non-equal.  Although @code{mpq_cmp} can be used for the same purpose, this
                   1524: function is much faster.
                   1525: @end deftypefun
                   1526:
                   1527: @node Applying Integer Functions, Miscellaneous Rational Functions, Comparing Rationals, Rational Number Functions
                   1528: @comment  node-name,  next,  previous,  up
                   1529: @section Applying Integer Functions to Rationals
                   1530:
                   1531: The set of @code{mpq} functions is quite small.  In particular, there are no
                   1532: functions for either input or output.  But there are two macros that allow us
                   1533: to apply any @code{mpz} function on the numerator or denominator of a rational
                   1534: number.  If these macros are used to assign to the rational number,
                   1535: @code{mpq_canonicalize} normally need to be called afterwards.
                   1536:
                   1537: @deftypefn Macro mpz_t mpq_numref (mpq_t @var{op})
                   1538: @deftypefnx Macro mpz_t mpq_denref (mpq_t @var{op})
                   1539: Return a reference to the numerator and denominator of @var{op}, respectively.
                   1540: The @code{mpz} functions can be used on the result of these macros.
                   1541: @end deftypefn
                   1542:
                   1543: @need 2000
                   1544: @node Miscellaneous Rational Functions, , Applying Integer Functions, Rational Number Functions
                   1545: @comment  node-name,  next,  previous,  up
                   1546: @section Miscellaneous Functions
                   1547:
                   1548: @deftypefun double mpq_get_d (mpq_t @var{op})
                   1549: Convert @var{op} to a double.
                   1550: @end deftypefun
                   1551:
                   1552: These functions assign between either the numerator or denominator of a
                   1553: rational, and an integer.  Instead of using these functions, it is preferable
                   1554: to use the more general mechanisms @code{mpq_numref} and @code{mpq_denref},
                   1555: together with @code{mpz_set}.
                   1556:
                   1557: @deftypefun void mpq_set_num (mpq_t @var{rational}, mpz_t @var{numerator})
                   1558: Copy @var{numerator} to the numerator of @var{rational}.  When this risks to
                   1559: make the numerator and denominator of @var{rational} have common factors, you
                   1560: have to pass @var{rational} to @code{mpq_canonicalize} before any operations
                   1561: are performed on @var{rational}.
                   1562:
                   1563: This function is equivalent to
                   1564: @code{mpz_set (mpq_numref (@var{rational}), @var{numerator})}.
                   1565: @end deftypefun
                   1566:
                   1567: @deftypefun void mpq_set_den (mpq_t @var{rational}, mpz_t @var{denominator})
                   1568: Copy @var{denominator} to the denominator of @var{rational}.  When this risks
                   1569: to make the numerator and denominator of @var{rational} have common factors,
                   1570: or if the denominator might be negative, you have to pass @var{rational} to
                   1571: @code{mpq_canonicalize} before any operations are performed on @var{rational}.
                   1572:
                   1573: @strong{In version 1 of the library, negative denominators were handled by
                   1574: copying the sign to the numerator.  That is no longer done.}
                   1575:
                   1576: This function is equivalent to
                   1577: @code{mpz_set (mpq_denref (@var{rational}), @var{denominators})}.
                   1578: @end deftypefun
                   1579:
                   1580: @deftypefun void mpq_get_num (mpz_t @var{numerator}, mpq_t @var{rational})
                   1581: Copy the numerator of @var{rational} to the integer @var{numerator}, to
                   1582: prepare for integer operations on the numerator.
                   1583:
                   1584: This function is equivalent to
                   1585: @code{mpz_set (@var{numerator}, mpq_numref (@var{rational}))}.
                   1586: @end deftypefun
                   1587:
                   1588: @deftypefun void mpq_get_den (mpz_t @var{denominator}, mpq_t @var{rational})
                   1589: Copy the denominator of @var{rational} to the integer @var{denominator}, to
                   1590: prepare for integer operations on the denominator.
                   1591:
                   1592: This function is equivalent to
                   1593: @code{mpz_set (@var{denominator}, mpq_denref (@var{rational}))}.
                   1594: @end deftypefun
                   1595:
                   1596:
                   1597: @node Floating-point Functions, Low-level Functions, Rational Number Functions, Top
                   1598: @comment  node-name,  next,  previous,  up
                   1599: @chapter Floating-point Functions
                   1600: @cindex Floating-point functions
                   1601: @cindex Float functions
                   1602:
                   1603: This is a description of the @emph{preliminary} interface for floating-point
                   1604: arithmetic in GNU MP 2.
                   1605:
                   1606: The floating-point functions expect arguments of type @code{mpf_t}.
                   1607:
                   1608: The MP floating-point functions have an interface that is similar to the MP
                   1609: integer functions.  The function prefix for floating-point operations is
                   1610: @code{mpf_}.
                   1611:
                   1612: There is one significant characteristic of floating-point numbers that has
                   1613: motivated a difference between this function class and other MP function
                   1614: classes: the inherent inexactness of floating point arithmetic.  The user has
                   1615: to specify the precision of each variable.  A computation that assigns a
                   1616: variable will take place with the precision of the assigned variable; the
                   1617: precision of variables used as input is ignored.
                   1618:
                   1619: @cindex User-defined precision
                   1620: The precision of a calculation is defined as follows: Compute the requested
                   1621: operation exactly (with ``infinite precision''), and truncate the result to
                   1622: the destination variable precision.  Even if the user has asked for a very
                   1623: high precision, MP will not calculate with superfluous digits.  For example,
                   1624: if two low-precision numbers of nearly equal magnitude are added, the
                   1625: precision of the result will be limited to what is required to represent the
                   1626: result accurately.
                   1627:
                   1628: The MP floating-point functions are @emph{not} intended as a smooth extension
                   1629: to the IEEE P754 arithmetic.  Specifically, the results obtained on one
                   1630: computer often differs from the results obtained on a computer with a
                   1631: different word size.
                   1632:
                   1633: @menu
                   1634: * Initializing Floats::
                   1635: * Assigning Floats::
                   1636: * Simultaneous Float Init & Assign::
                   1637: * Converting Floats::
                   1638: * Float Arithmetic::
                   1639: * Float Comparison::
                   1640: * I/O of Floats::
                   1641: * Miscellaneous Float Functions::
                   1642: @end menu
                   1643:
                   1644: @node Initializing Floats, Assigning Floats, , Floating-point Functions
                   1645: @comment  node-name,  next,  previous,  up
                   1646: @section Initialization and Assignment Functions
                   1647:
                   1648: @deftypefun void mpf_set_default_prec (unsigned long int @var{prec})
                   1649: Set the default precision to be @strong{at least} @var{prec} bits.  All
                   1650: subsequent calls to @code{mpf_init} will use this precision, but previously
                   1651: initialized variables are unaffected.
                   1652: @end deftypefun
                   1653:
                   1654: An @code{mpf_t} object must be initialized before storing the first value in
                   1655: it.  The functions @code{mpf_init} and @code{mpf_init2} are used for that
                   1656: purpose.
                   1657:
                   1658: @deftypefun void mpf_init (mpf_t @var{x})
                   1659: Initialize @var{x} to 0.  Normally, a variable should be initialized once only
                   1660: or at least be cleared, using @code{mpf_clear}, between initializations.  The
                   1661: precision of @var{x} is undefined unless a default precision has already been
                   1662: established by a call to @code{mpf_set_default_prec}.
                   1663: @end deftypefun
                   1664:
                   1665: @deftypefun void mpf_init2 (mpf_t @var{x}, unsigned long int @var{prec})
                   1666: Initialize @var{x} to 0 and set its precision to be @strong{at least}
                   1667: @var{prec} bits.  Normally, a variable should be initialized once only or at
                   1668: least be cleared, using @code{mpf_clear}, between initializations.
                   1669: @end deftypefun
                   1670:
                   1671: @deftypefun void mpf_clear (mpf_t @var{x})
                   1672: Free the space occupied by @var{x}.  Make sure to call this function for all
                   1673: @code{mpf_t} variables when you are done with them.
                   1674: @end deftypefun
                   1675:
                   1676: @need 2000
                   1677: Here is an example on how to initialize floating-point variables:
                   1678: @example
                   1679: @{
                   1680:   mpf_t x, y;
                   1681:   mpf_init (x);                        /* use default precision */
                   1682:   mpf_init2 (y, 256);          /* precision @emph{at least} 256 bits */
                   1683:   @dots{}
                   1684:   /* Unless the program is about to exit, do ... */
                   1685:   mpf_clear (x);
                   1686:   mpf_clear (y);
                   1687: @}
                   1688: @end example
                   1689:
                   1690: The following three functions are useful for changing the precision during a
                   1691: calculation.  A typical use would be for adjusting the precision gradually in
                   1692: iterative algorithms like Newton-Raphson, making the computation precision
                   1693: closely match the actual accurate part of the numbers.
                   1694:
                   1695: @deftypefun void mpf_set_prec (mpf_t @var{rop}, unsigned long int @var{prec})
                   1696: Set the precision of @var{rop} to be @strong{at least} @var{prec} bits.
                   1697: Since changing the precision involves calls to @code{realloc}, this routine
                   1698: should not be called in a tight loop.
                   1699: @end deftypefun
                   1700:
                   1701: @deftypefun {unsigned long int} mpf_get_prec (mpf_t @var{op})
                   1702: Return the precision actually used for assignments of @var{op}.
                   1703: @end deftypefun
                   1704:
                   1705: @deftypefun void mpf_set_prec_raw (mpf_t @var{rop}, unsigned long int @var{prec})
                   1706: Set the precision of @var{rop} to be @strong{at least} @var{prec} bits.  This
                   1707: is a low-level function that does not change the allocation.  The @var{prec}
                   1708: argument must not be larger that the precision previously returned by
                   1709: @code{mpf_get_prec}.  It is crucial that the precision of @var{rop} is
                   1710: ultimately reset to exactly the value returned by @code{mpf_get_prec}.
                   1711: @end deftypefun
                   1712:
                   1713:
                   1714: @node Assigning Floats, Simultaneous Float Init & Assign, Initializing Floats, Floating-point Functions
                   1715: @comment  node-name,  next,  previous,  up
                   1716: @subsection Assignment Functions
                   1717: @cindex Float assignment functions
                   1718:
                   1719: These functions assign new values to already initialized floats
                   1720: (@pxref{Initializing Floats}).
                   1721:
                   1722: @deftypefun void mpf_set (mpf_t @var{rop}, mpf_t @var{op})
                   1723: @deftypefunx void mpf_set_ui (mpf_t @var{rop}, unsigned long int @var{op})
                   1724: @deftypefunx void mpf_set_si (mpf_t @var{rop}, signed long int @var{op})
                   1725: @deftypefunx void mpf_set_d (mpf_t @var{rop}, double @var{op})
                   1726: @deftypefunx void mpf_set_z (mpf_t @var{rop}, mpz_t @var{op})
                   1727: @deftypefunx void mpf_set_q (mpf_t @var{rop}, mpq_t @var{op})
                   1728: Set the value of @var{rop} from @var{op}.
                   1729: @end deftypefun
                   1730:
                   1731: @deftypefun int mpf_set_str (mpf_t @var{rop}, char *@var{str}, int @var{base})
                   1732: Set the value of @var{rop} from the string in @var{str}.  The string is of the
                   1733: form @samp{M@@N} or, if the base is 10 or less, alternatively @samp{MeN}.
                   1734: @samp{M} is the mantissa and @samp{N} is the exponent.  The mantissa is always
                   1735: in the specified base.  The exponent is either in the specified base or, if
                   1736: @var{base} is negative, in decimal.
                   1737:
                   1738: The argument @var{base} may be in the ranges 2 to 36, or @minus{}36 to
                   1739: @minus{}2.  Negative values are used to specify that the exponent is in
                   1740: decimal.
                   1741:
                   1742: Unlike the corresponding @code{mpz} function, the base will not be determined
                   1743: from the leading characters of the string if @var{base} is 0.  This is so that
                   1744: numbers like @samp{0.23} are not interpreted as octal.
                   1745:
                   1746: White space is allowed in the string, and is simply ignored.
                   1747:
                   1748: This function returns 0 if the entire string up to the '\0' is a valid number
                   1749: in base @var{base}.  Otherwise it returns @minus{}1.
                   1750: @end deftypefun
                   1751:
                   1752:
                   1753: @node Simultaneous Float Init & Assign, Converting Floats, Assigning Floats, Floating-point Functions
                   1754: @comment  node-name,  next,  previous,  up
                   1755: @subsection Combined Initialization and Assignment Functions
                   1756: @cindex Initialization and assignment functions
                   1757:
                   1758: For convenience, MP provides a parallel series of initialize-and-set functions
                   1759: which initialize the output and then store the value there.  These functions'
                   1760: names have the form @code{mpf_init_set@dots{}}
                   1761:
                   1762: Once the float has been initialized by any of the @code{mpf_init_set@dots{}}
                   1763: functions, it can be used as the source or destination operand for the ordinary
                   1764: float functions.  Don't use an initialize-and-set function on a variable
                   1765: already initialized!
                   1766:
                   1767: @deftypefun void mpf_init_set (mpf_t @var{rop}, mpf_t @var{op})
                   1768: @deftypefunx void mpf_init_set_ui (mpf_t @var{rop}, unsigned long int @var{op})
                   1769: @deftypefunx void mpf_init_set_si (mpf_t @var{rop}, signed long int @var{op})
                   1770: @deftypefunx void mpf_init_set_d (mpf_t @var{rop}, double @var{op})
                   1771: Initialize @var{rop} and set its value from @var{op}.
                   1772:
                   1773: The precision of @var{rop} will be taken from the active default precision, as
                   1774: set by @code{mpf_set_default_prec}.
                   1775: @end deftypefun
                   1776:
                   1777: @deftypefun int mpf_init_set_str (mpf_t @var{rop}, char *@var{str}, int @var{base})
                   1778: Initialize @var{rop} and set its value from the string in @var{str}.  See
                   1779: @code{mpf_set_str} above for details on the assignment operation.
                   1780:
                   1781: Note that @var{rop} is initialized even if an error occurs.  (I.e., you have to
                   1782: call @code{mpf_clear} for it.)
                   1783:
                   1784: The precision of @var{rop} will be taken from the active default precision, as
                   1785: set by @code{mpf_set_default_prec}.
                   1786: @end deftypefun
                   1787:
                   1788:
                   1789: @node Converting Floats, Float Arithmetic, Simultaneous Float Init & Assign, Floating-point Functions
                   1790: @comment  node-name,  next,  previous,  up
                   1791: @section Conversion Functions
                   1792: @cindex Conversion functions
                   1793:
                   1794: @deftypefun double mpf_get_d (mpf_t @var{op})
                   1795: Convert @var{op} to a double.
                   1796: @end deftypefun
                   1797:
                   1798: @deftypefun {char *} mpf_get_str (char *@var{str}, mp_exp_t *@var{expptr}, int @var{base}, size_t @var{n_digits}, mpf_t @var{op})
                   1799: Convert @var{op} to a string of digits in base @var{base}.  The base may vary
                   1800: from 2 to 36.  Generate at most @var{n_digits} significant digits, or if
                   1801: @var{n_digits} is 0, the maximum number of digits accurately representable by
                   1802: @var{op}.
                   1803:
                   1804: If @var{str} is NULL, space for the mantissa is allocated using the default
                   1805: allocation function, and a pointer to the string is returned.
                   1806:
                   1807: If @var{str} is not NULL, it should point to a block of storage enough large
                   1808: for the mantissa, i.e., @var{n_digits} + 2.  The two extra bytes are for a
                   1809: possible minus sign, and for the terminating null character.
                   1810:
                   1811: The exponent is written through the pointer @var{expptr}.
                   1812:
                   1813: If @var{n_digits} is 0, the maximum number of digits meaningfully achievable
                   1814: from the precision of @var{op} will be generated.  Note that the space
                   1815: requirements for @var{str} in this case will be impossible for the user to
                   1816: predetermine.  Therefore, you need to pass NULL for the string argument
                   1817: whenever @var{n_digits} is 0.
                   1818:
                   1819: The generated string is a fraction, with an implicit radix point immediately
                   1820: to the left of the first digit.  For example, the number 3.1416 would be
                   1821: returned as "31416" in the string and 1 written at @var{expptr}.
                   1822: @end deftypefun
                   1823:
                   1824:
                   1825: @node Float Arithmetic, Float Comparison, Converting Floats, Floating-point Functions
                   1826: @comment  node-name,  next,  previous,  up
                   1827: @section Arithmetic Functions
                   1828: @cindex Float arithmetic functions
                   1829: @cindex Arithmetic functions
                   1830:
                   1831: @deftypefun void mpf_add (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
                   1832: @deftypefunx void mpf_add_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
                   1833: @ifinfo
                   1834: Set @var{rop} to @var{op1} + @var{op2}.
                   1835: @end ifinfo
                   1836: @iftex
                   1837: @tex
                   1838: Set @var{rop} to $@var{op1} + @var{op2}$.
                   1839: @end tex
                   1840: @end iftex
                   1841: @end deftypefun
                   1842:
                   1843: @deftypefun void mpf_sub (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
                   1844: @deftypefunx void mpf_ui_sub (mpf_t @var{rop}, unsigned long int @var{op1}, mpf_t @var{op2})
                   1845: @deftypefunx void mpf_sub_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
                   1846: Set @var{rop} to @var{op1} @minus{} @var{op2}.
                   1847: @end deftypefun
                   1848:
                   1849: @deftypefun void mpf_mul (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
                   1850: @deftypefunx void mpf_mul_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
                   1851: @ifinfo
                   1852: Set @var{rop} to @var{op1} times @var{op2}.
                   1853: @end ifinfo
                   1854: @iftex
                   1855: @tex
                   1856: Set @var{rop} to $@var{op1} \times @var{op2}$.
                   1857: @end tex
                   1858: @end iftex
                   1859: @end deftypefun
                   1860:
                   1861: Division is undefined if the divisor is zero, and passing a zero divisor to
                   1862: the divide functions will make these functions intentionally divide by zero.
                   1863: This gives the user the possibility to handle arithmetic exceptions in these
                   1864: functions in the same manner as other arithmetic exceptions.
                   1865:
                   1866: @deftypefun void mpf_div (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
                   1867: @deftypefunx void mpf_ui_div (mpf_t @var{rop}, unsigned long int @var{op1}, mpf_t @var{op2})
                   1868: @deftypefunx void mpf_div_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
                   1869: Set @var{rop} to @var{op1}/@var{op2}.
                   1870: @end deftypefun
                   1871:
                   1872: @deftypefun void mpf_sqrt (mpf_t @var{rop}, mpf_t @var{op})
                   1873: @deftypefunx void mpf_sqrt_ui (mpf_t @var{rop}, unsigned long int @var{op})
                   1874: @ifinfo
                   1875: Set @var{rop} to the square root of @var{op}.
                   1876: @end ifinfo
                   1877: @iftex
                   1878: @tex
                   1879: Set @var{rop} to $\sqrt{@var{op}}$.
                   1880: @end tex
                   1881: @end iftex
                   1882: @end deftypefun
                   1883:
                   1884: @c @deftypefun void mpf_pow_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
                   1885: @c Set @var{rop} to @var{op1} raised to @var{op2}.
                   1886: @c @end deftypefun
                   1887:
                   1888: @deftypefun void mpf_neg (mpf_t @var{rop}, mpf_t @var{op})
                   1889: Set @var{rop} to @minus{}@var{op}.
                   1890: @end deftypefun
                   1891:
                   1892: @deftypefun void mpf_abs (mpf_t @var{rop}, mpf_t @var{op})
                   1893: Set @var{rop} to the absolute value of @var{op}.
                   1894: @end deftypefun
                   1895:
                   1896: @deftypefun void mpf_mul_2exp (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
                   1897: @ifinfo
                   1898: Set @var{rop} to @var{op1} times 2 raised to @var{op2}.
                   1899: @end ifinfo
                   1900: @iftex
                   1901: @tex
                   1902: Set @var{rop} to $@var{op1} \times 2^{op2}$.
                   1903: @end tex
                   1904: @end iftex
                   1905: @end deftypefun
                   1906:
                   1907: @deftypefun void mpf_div_2exp (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2})
                   1908: @ifinfo
                   1909: Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}.
                   1910: @end ifinfo
                   1911: @iftex
                   1912: @tex
                   1913: Set @var{rop} to $@var{op1}/2^{op2}$.
                   1914: @end tex
                   1915: @end iftex
                   1916: @end deftypefun
                   1917:
                   1918: @node Float Comparison, I/O of Floats, Float Arithmetic, Floating-point Functions
                   1919: @comment  node-name,  next,  previous,  up
                   1920: @section Comparison Functions
                   1921: @cindex Float comparisons functions
                   1922: @cindex Comparison functions
                   1923:
                   1924: @deftypefun int mpf_cmp (mpf_t @var{op1}, mpf_t @var{op2})
                   1925: @deftypefunx int mpf_cmp_ui (mpf_t @var{op1}, unsigned long int @var{op2})
                   1926: @deftypefunx int mpf_cmp_si (mpf_t @var{op1}, signed long int @var{op2})
                   1927: @ifinfo
                   1928: Compare @var{op1} and @var{op2}.  Return a positive value if @var{op1} >
                   1929: @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} <
                   1930: @var{op2}.
                   1931: @end ifinfo
                   1932: @iftex
                   1933: @tex
                   1934: Compare @var{op1} and @var{op2}.  Return a positive value if $@var{op1} >
                   1935: @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1}
                   1936: < @var{op2}$.
                   1937: @end tex
                   1938: @end iftex
                   1939: @end deftypefun
                   1940:
                   1941: @deftypefun int mpf_eq (mpf_t @var{op1}, mpf_t @var{op2}, unsigned long int op3)
                   1942: Return non-zero if the first @var{op3} bits of @var{op1} and @var{op2} are
                   1943: equal, zero otherwise.  I.e., test of @var{op1} and @var{op2} are
                   1944: approximately equal.
                   1945: @end deftypefun
                   1946:
                   1947: @deftypefun void mpf_reldiff (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2})
                   1948: Compute the relative difference between @var{op1} and @var{op2} and store the
                   1949: result in @var{rop}.
                   1950: @end deftypefun
                   1951:
                   1952: @deftypefn Macro int mpf_sgn (mpf_t @var{op})
                   1953: @ifinfo
                   1954: Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0.
                   1955: @end ifinfo
                   1956: @iftex
                   1957: @tex
                   1958: Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$.
                   1959: @end tex
                   1960: @end iftex
                   1961:
                   1962: This function is actually implemented as a macro.  It evaluates its
                   1963: arguments multiple times.
                   1964: @end deftypefn
                   1965:
                   1966: @node I/O of Floats, Miscellaneous Float Functions, Float Comparison, Floating-point Functions
                   1967: @comment  node-name,  next,  previous,  up
                   1968: @section Input and Output Functions
                   1969: @cindex Float input and output functions
                   1970: @cindex Input functions
                   1971: @cindex Output functions
                   1972: @cindex I/O functions
                   1973:
                   1974: Functions that perform input from a stdio stream, and functions that output to
                   1975: a stdio stream.  Passing a NULL pointer for a @var{stream} argument to any of
                   1976: these functions will make them read from @code{stdin} and write to
                   1977: @code{stdout}, respectively.
                   1978:
                   1979: When using any of these functions, it is a good idea to include @file{stdio.h}
                   1980: before @file{gmp.h}, since that will allow @file{gmp.h} to define prototypes
                   1981: for these functions.
                   1982:
                   1983: @deftypefun size_t mpf_out_str (FILE *@var{stream}, int @var{base}, size_t @var{n_digits}, mpf_t @var{op})
                   1984: Output @var{op} on stdio stream @var{stream}, as a string of digits in
                   1985: base @var{base}.  The base may vary from 2 to 36.  Print at most
                   1986: @var{n_digits} significant digits, or if @var{n_digits} is 0, the maximum
                   1987: number of digits accurately representable by @var{op}.
                   1988:
                   1989: In addition to the significant digits, a leading @samp{0.} and a
                   1990: trailing exponent, in the form @samp{eNNN}, are printed.  If @var{base}
                   1991: is greater than 10, @samp{@@} will be used instead of @samp{e} as
                   1992: exponent delimiter.
                   1993:
                   1994: Return the number of bytes written, or if an error occurred, return 0.
                   1995: @end deftypefun
                   1996:
                   1997: @deftypefun size_t mpf_inp_str (mpf_t @var{rop}, FILE *@var{stream}, int @var{base})
                   1998: Input a string in base @var{base} from stdio stream @var{stream}, and put the
                   1999: read float in @var{rop}.  The string is of the form @samp{M@@N} or, if the
                   2000: base is 10 or less, alternatively @samp{MeN}.  @samp{M} is the mantissa and
                   2001: @samp{N} is the exponent.  The mantissa is always in the specified base.  The
                   2002: exponent is either in the specified base or, if @var{base} is negative, in
                   2003: decimal.
                   2004:
                   2005: The argument @var{base} may be in the ranges 2 to 36, or @minus{}36 to
                   2006: @minus{}2.  Negative values are used to specify that the exponent is in
                   2007: decimal.
                   2008:
                   2009: Unlike the corresponding @code{mpz} function, the base will not be determined
                   2010: from the leading characters of the string if @var{base} is 0.  This is so that
                   2011: numbers like @samp{0.23} are not interpreted as octal.
                   2012:
                   2013: Return the number of bytes read, or if an error occurred, return 0.
                   2014: @end deftypefun
                   2015:
                   2016: @c @deftypefun void mpf_out_raw (FILE *@var{stream}, mpf_t @var{float})
                   2017: @c Output @var{float} on stdio stream @var{stream}, in raw binary
                   2018: @c format.  The float is written in a portable format, with 4 bytes of
                   2019: @c size information, and that many bytes of limbs.  Both the size and the
                   2020: @c limbs are written in decreasing significance order.
                   2021: @c @end deftypefun
                   2022:
                   2023: @c @deftypefun void mpf_inp_raw (mpf_t @var{float}, FILE *@var{stream})
                   2024: @c Input from stdio stream @var{stream} in the format written by
                   2025: @c @code{mpf_out_raw}, and put the result in @var{float}.
                   2026: @c @end deftypefun
                   2027:
                   2028:
                   2029: @node Miscellaneous Float Functions, , I/O of Floats, Floating-point Functions
                   2030: @comment  node-name,  next,  previous,  up
                   2031: @section Miscellaneous Functions
                   2032: @cindex Miscellaneous float functions
                   2033:
                   2034: @deftypefun void mpf_random2 (mpf_t @var{rop}, mp_size_t @var{max_size}, mp_exp_t @var{max_exp})
                   2035: Generate a random float of at most @var{max_size} limbs, with long strings of
                   2036: zeros and ones in the binary representation.  The exponent of the number is in
                   2037: the interval @minus{}@var{exp} to @var{exp}.  This function is useful for
                   2038: testing functions and algorithms, since this kind of random numbers have
                   2039: proven to be more likely to trigger corner-case bugs.  Negative random numbers
                   2040: are generated when @var{max_size} is negative.
                   2041: @end deftypefun
                   2042:
                   2043: @c @deftypefun size_t mpf_size (mpf_t @var{op})
                   2044: @c Return the size of @var{op} measured in number of limbs.  If @var{op} is
                   2045: @c zero, the returned value will be zero.  (@xref{Nomenclature}, for an
                   2046: @c explanation of the concept @dfn{limb}.)
                   2047: @c
                   2048: @c @strong{This function is obsolete.  It will disappear from future MP
                   2049: @c releases.}
                   2050: @c @end deftypefun
                   2051:
                   2052: @node Low-level Functions, BSD Compatible Functions, Floating-point Functions, Top
                   2053: @comment  node-name,  next,  previous,  up
                   2054: @chapter Low-level Functions
                   2055: @cindex Low-level functions
                   2056:
                   2057: This chapter describes low-level MP functions, used to implement the high-level
                   2058: MP functions, but also intended for time-critical user code.
                   2059:
                   2060: These functions start with the prefix @code{mpn_}.
                   2061:
                   2062: @c 1. Some of these function clobber input operands.
                   2063: @c
                   2064:
                   2065: The @code{mpn} functions are designed to be as fast as possible, @strong{not}
                   2066: to provide a coherent calling interface.  The different functions have somewhat
                   2067: similar interfaces, but there are variations that make them hard to use.  These
                   2068: functions do as little as possible apart from the real multiple precision
                   2069: computation, so that no time is spent on things that not all callers need.
                   2070:
                   2071: A source operand is specified by a pointer to the least significant limb and a
                   2072: limb count.  A destination operand is specified by just a pointer.  It is the
                   2073: responsibility of the caller to ensure that the destination has enough space
                   2074: for storing the result.
                   2075:
                   2076: With this way of specifying operands, it is possible to perform computations
                   2077: on subranges of an argument, and store the result into a subrange of a
                   2078: destination.
                   2079:
                   2080: A common requirement for all functions is that each source area needs at least
                   2081: one limb.  No size argument may be zero.
                   2082:
                   2083: The @code{mpn} functions is the base for the implementation of the @code{mpz_},
                   2084: @code{mpf_}, and @code{mpq_} functions.
                   2085:
                   2086: This example adds the number beginning at @var{src1_ptr} and the number
                   2087: beginning at @var{src2_ptr} and writes the sum at @var{dest_ptr}.  All areas
                   2088: have @var{size} limbs.
                   2089:
                   2090: @example
                   2091: cy = mpn_add_n (dest_ptr, src1_ptr, src2_ptr, size)
                   2092: @end example
                   2093:
                   2094: @noindent
                   2095: In the notation used here, a source operand is identified by the pointer to
                   2096: the least significant limb, and the limb count in braces.  For example,
                   2097: @{s1_ptr, s1_size@}.
                   2098:
                   2099: @deftypefun mp_limb_t mpn_add_n (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{size})
                   2100: Add @{@var{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@}, and
                   2101: write the @var{size} least significant limbs of the result to @var{dest_ptr}.
                   2102: Return carry, either 0 or 1.
                   2103:
                   2104: This is the lowest-level function for addition.  It is the preferred function
                   2105: for addition, since it is written in assembly for most targets.  For addition
                   2106: of a variable to itself (i.e., @var{src1_ptr} equals @var{src2_ptr}, use
                   2107: @code{mpn_lshift} with a count of 1 for optimal speed.
                   2108: @end deftypefun
                   2109:
                   2110: @deftypefun mp_limb_t mpn_add_1 (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{size}, mp_limb_t @var{src2_limb})
                   2111: Add @{@var{src1_ptr}, @var{size}@} and @var{src2_limb}, and write the
                   2112: @var{size} least significant limbs of the result to @var{dest_ptr}.  Return
                   2113: carry, either 0 or 1.
                   2114: @end deftypefun
                   2115:
                   2116: @deftypefun mp_limb_t mpn_add (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{src1_size}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{src2_size})
                   2117: Add @{@var{src1_ptr}, @var{src1_size}@} and @{@var{src2_ptr},
                   2118: @var{src2_size}@}, and write the @var{src1_size} least significant limbs of
                   2119: the result to @var{dest_ptr}.  Return carry, either 0 or 1.
                   2120:
                   2121: This function requires that @var{src1_size} is greater than or equal to
                   2122: @var{src2_size}.
                   2123: @end deftypefun
                   2124:
                   2125: @deftypefun mp_limb_t mpn_sub_n (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{size})
                   2126: Subtract @{@var{src2_ptr}, @var{src2_size}@} from @{@var{src1_ptr},
                   2127: @var{size}@}, and write the @var{size} least significant limbs of the result
                   2128: to @var{dest_ptr}.  Return borrow, either 0 or 1.
                   2129:
                   2130: This is the lowest-level function for subtraction.  It is the preferred
                   2131: function for subtraction, since it is written in assembly for most targets.
                   2132: @end deftypefun
                   2133:
                   2134: @deftypefun mp_limb_t mpn_sub_1 (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{size}, mp_limb_t @var{src2_limb})
                   2135: Subtract @var{src2_limb} from @{@var{src1_ptr}, @var{size}@}, and write the
                   2136: @var{size} least significant limbs of the result to @var{dest_ptr}.  Return
                   2137: borrow, either 0 or 1.
                   2138: @end deftypefun
                   2139:
                   2140: @deftypefun mp_limb_t mpn_sub (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{src1_size}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{src2_size})
                   2141: Subtract @{@var{src2_ptr}, @var{src2_size}@} from @{@var{src1_ptr},
                   2142: @var{src1_size}@}, and write the @var{src1_size} least significant limbs of
                   2143: the result to @var{dest_ptr}.  Return borrow, either 0 or 1.
                   2144:
                   2145: This function requires that @var{src1_size} is greater than or equal to
                   2146: @var{src2_size}.
                   2147: @end deftypefun
                   2148:
                   2149: @deftypefun void mpn_mul_n (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{size})
                   2150: Multiply @{@var{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@},
                   2151: and write the @strong{entire} result to @var{dest_ptr}.
                   2152:
                   2153: The destination has to have space for 2@var{size} limbs, even if the
                   2154: significant result might be one limb smaller.
                   2155: @end deftypefun
                   2156:
                   2157: @deftypefun mp_limb_t mpn_mul_1 (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{size}, mp_limb_t @var{src2_limb})
                   2158: Multiply @{@var{src1_ptr}, @var{size}@} and @var{src2_limb}, and write the
                   2159: @var{size} least significant limbs of the product to @var{dest_ptr}.  Return
                   2160: the most significant limb of the product.
                   2161:
                   2162: This is a low-level function that is a building block for general
                   2163: multiplication as well as other operations in MP.  It is written in assembly
                   2164: for most targets.
                   2165:
                   2166: Don't call this function if @var{src2_limb} is a power of 2; use
                   2167: @code{mpn_lshift} with a count equal to the logarithm of @var{src2_limb}
                   2168: instead, for optimal speed.
                   2169: @end deftypefun
                   2170:
                   2171: @deftypefun mp_limb_t mpn_addmul_1 (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{size}, mp_limb_t @var{src2_limb})
                   2172: Multiply @{@var{src1_ptr}, @var{size}@} and @var{src2_limb}, and add the
                   2173: @var{size} least significant limbs of the product to @{@var{dest_ptr},
                   2174: @var{size}@} and write the result to @var{dest_ptr} @var{dest_ptr}.  Return
                   2175: the most significant limb of the product, plus carry-out from the addition.
                   2176:
                   2177: This is a low-level function that is a building block for general
                   2178: multiplication as well as other operations in MP.  It is written in assembly
                   2179: for most targets.
                   2180: @end deftypefun
                   2181:
                   2182: @deftypefun mp_limb_t mpn_submul_1 (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{size}, mp_limb_t @var{src2_limb})
                   2183: Multiply @{@var{src1_ptr}, @var{size}@} and @var{src2_limb}, and subtract the
                   2184: @var{size} least significant limbs of the product from @{@var{dest_ptr},
                   2185: @var{size}@} and write the result to @var{dest_ptr}.  Return the most
                   2186: significant limb of the product, minus borrow-out from the subtraction.
                   2187:
                   2188: This is a low-level function that is a building block for general
                   2189: multiplication and division as well as other operations in MP.  It is written
                   2190: in assembly for most targets.
                   2191: @end deftypefun
                   2192:
                   2193: @deftypefun mp_limb_t mpn_mul (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src1_ptr}, mp_size_t @var{src1_size}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{src2_size})
                   2194: Multiply @{@var{src1_ptr}, @var{src1_size}@} and @{@var{src2_ptr},
                   2195: @var{src2_size}@}, and write the result to @var{dest_ptr}.  Return the most
                   2196: significant limb of the result.
                   2197:
                   2198: The destination has to have space for @var{src1_size} + @var{src1_size}
                   2199: limbs, even if the result might be one limb smaller.
                   2200:
                   2201: This function requires that @var{src1_size} is greater than or equal to
                   2202: @var{src2_size}.  The destination must be distinct from either input operands.
                   2203: @end deftypefun
                   2204:
                   2205: @deftypefun mp_size_t mpn_divrem (mp_limb_t * @var{r1p}, mp_size_t @var{xsize}, mp_limb_t * @var{rs2p}, mp_size_t @var{rs2size}, const mp_limb_t * @var{s3p}, mp_size_t @var{s3size})
                   2206: Divide @{@var{rs2p}, @var{rs2size}@} by @{@var{s3p}, @var{s3size}@}, and
                   2207: write the quotient at @var{r1p}, with the exception of the most significant
                   2208: limb, which is returned.  The remainder replaces the dividend at @var{rs2p}.
                   2209:
                   2210: In addition to an integer quotient, @var{xsize} fraction limbs are developed,
                   2211: and stored after the integral limbs.  For most usages, @var{xsize} will be
                   2212: zero.
                   2213:
                   2214: It is required that @var{rs2size} is greater than or equal to @var{s3size}.
                   2215: It is required that the most significant bit of the divisor is set.
                   2216:
                   2217: If the quotient is not needed, pass @var{rs2p} + @var{s3size} as @var{r1p}.
                   2218: Aside from that special case, no overlap between arguments is permitted.
                   2219:
                   2220: Return the most significant limb of the quotient, either 0 or 1.
                   2221:
                   2222: The area at @var{r1p} needs to be @var{rs2size} @minus{} @var{s3size} +
                   2223: @var{xsize} limbs large.
                   2224: @end deftypefun
                   2225:
                   2226: @deftypefun mp_limb_t mpn_divrem_1 (mp_limb_t * @var{r1p}, mp_size_t @var{xsize}, mp_limb_t * @var{s2p}, mp_size_t @var{s2size}, mp_limb_t @var{s3limb})
                   2227: Divide @{@var{s2p}, @var{s2size}@} by @var{s3limb}, and write the quotient
                   2228: at @var{r1p}.  Return the remainder.
                   2229:
                   2230: In addition to an integer quotient, @var{xsize} fraction limbs are developed,
                   2231: and stored after the integral limbs.  For most usages, @var{xsize} will be
                   2232: zero.
                   2233:
                   2234: The areas at @var{r1p} and @var{s2p} have to be identical or completely
                   2235: separate, not partially overlapping.
                   2236: @end deftypefun
                   2237:
                   2238: @deftypefun mp_size_t mpn_divmod (mp_limb_t * @var{r1p}, mp_limb_t * @var{rs2p}, mp_size_t @var{rs2size}, const mp_limb_t * @var{s3p}, mp_size_t @var{s3size})
                   2239: @strong{This interface is obsolete.  It will disappear from future releases.
                   2240: Use @code{mpn_divrem} in its stead.}
                   2241: @end deftypefun
                   2242:
                   2243: @deftypefun mp_limb_t mpn_divmod_1 (mp_limb_t * @var{r1p}, mp_limb_t * @var{s2p}, mp_size_t @var{s2size}, mp_limb_t @var{s3limb})
                   2244: @strong{This interface is obsolete.  It will disappear from future releases.
                   2245: Use @code{mpn_divrem_1} in its stead.}
                   2246: @end deftypefun
                   2247:
                   2248: @deftypefun mp_limb_t mpn_mod_1 (mp_limb_t * @var{s1p}, mp_size_t @var{s1size}, mp_limb_t @var{s2limb})
                   2249: Divide @{@var{s1p}, @var{s1size}@} by @var{s2limb}, and return the remainder.
                   2250: @end deftypefun
                   2251:
                   2252: @deftypefun mp_limb_t mpn_preinv_mod_1 (mp_limb_t * @var{s1p}, mp_size_t @var{s1size}, mp_limb_t @var{s2limb}, mp_limb_t @var{s3limb})
                   2253: @strong{This interface is obsolete.  It will disappear from future releases.
                   2254: Use @code{mpn_mod_1} in its stead.}
                   2255: @end deftypefun
                   2256:
                   2257: @deftypefun mp_limb_t mpn_bdivmod (mp_limb_t * @var{dest_ptr}, mp_limb_t * @var{s1p}, mp_size_t @var{s1size}, const mp_limb_t * @var{s2p}, mp_size_t @var{s2size}, unsigned long int @var{d})
                   2258: The function puts the low [@var{d}/@var{BITS_PER_MP_LIMB}] limbs of
                   2259: @var{q} =
                   2260: @{@var{s1p}, @var{s1size}@}/@{@var{s2p}, @var{s2size}@}
                   2261: mod 2^@var{d}
                   2262: at @var{dest_ptr},
                   2263: and returns the high @var{d} mod @var{BITS_PER_MP_LIMB} bits of @var{q}.
                   2264:
                   2265: @{@var{s1p}, @var{s1size}@} - @var{q} * @{@var{s2p}, @var{s2size}@}
                   2266: mod 2^(@var{s1size}*@var{BITS_PER_MP_LIMB})
                   2267: is placed at @var{s1p}.
                   2268: Since the low [@var{d}/@var{BITS_PER_MP_LIMB}] limbs of
                   2269: this difference are zero, it is possible to overwrite the low limbs at
                   2270: @var{s1p} with this difference,
                   2271: provided @var{dest_ptr} <= @var{s1p}.
                   2272:
                   2273: This function requires that @var{s1size} * @var{BITS_PER_MP_LIMB} >= @var{D},
                   2274: and that @{@var{s2p}, @var{s2size}@} is odd.
                   2275:
                   2276: @strong{This interface is preliminary.  It might change incompatibly in
                   2277: future revisions.}
                   2278: @end deftypefun
                   2279:
                   2280: @deftypefun mp_limb_t mpn_lshift (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src_ptr}, mp_size_t @var{src_size}, unsigned long int @var{count})
                   2281: Shift @{@var{src_ptr}, @var{src_size}@} @var{count} bits to the left, and
                   2282: write the @var{src_size} least significant limbs of the result to
                   2283: @var{dest_ptr}.  @var{count} might be in the range 1 to n @minus{} 1, on an
                   2284: n-bit machine. The bits shifted out to the left are returned.
                   2285:
                   2286: Overlapping of the destination space and the source space is allowed in this
                   2287: function, provided @var{dest_ptr} >= @var{src_ptr}.
                   2288:
                   2289: This function is written in assembly for most targets.
                   2290: @end deftypefun
                   2291:
                   2292: @deftypefun mp_limp_t mpn_rshift (mp_limb_t * @var{dest_ptr}, const mp_limb_t * @var{src_ptr}, mp_size_t @var{src_size}, unsigned long int @var{count})
                   2293: Shift @{@var{src_ptr}, @var{src_size}@} @var{count} bits to the right, and
                   2294: write the @var{src_size} most significant limbs of the result to
                   2295: @var{dest_ptr}.  @var{count} might be in the range 1 to n @minus{} 1, on an
                   2296: n-bit machine.  The bits shifted out to the right are returned.
                   2297:
                   2298: Overlapping of the destination space and the source space is allowed in this
                   2299: function, provided @var{dest_ptr} <= @var{src_ptr}.
                   2300:
                   2301: This function is written in assembly for most targets.
                   2302: @end deftypefun
                   2303:
                   2304: @deftypefun int mpn_cmp (const mp_limb_t * @var{src1_ptr}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{size})
                   2305: Compare @{@var{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@} and
                   2306: return a positive value if src1 > src2, 0 of they are equal, and a negative
                   2307: value if src1 < src2.
                   2308: @end deftypefun
                   2309:
                   2310: @deftypefun mp_size_t mpn_gcd (mp_limb_t * @var{dest_ptr}, mp_limb_t * @var{src1_ptr}, mp_size_t @var{src1_size}, mp_limb_t * @var{src2_ptr}, mp_size_t @var{src2_size})
                   2311: Puts at @var{dest_ptr} the greatest common divisor of @{@var{src1_ptr},
                   2312: @var{src1_size}@} and @{@var{src2_ptr}, @var{src2_size}@}; both source
                   2313: operands are destroyed by the operation.  The size in limbs of the greatest
                   2314: common divisor is returned.
                   2315:
                   2316: @{@var{src1_ptr}, @var{src1_size}@} must be odd, and @{@var{src2_ptr},
                   2317: @var{src2_size}@} must have at least as many bits as @{@var{src1_ptr},
                   2318: @var{src1_size}@}.
                   2319:
                   2320: @strong{This interface is preliminary.  It might change incompatibly in
                   2321: future revisions.}
                   2322: @end deftypefun
                   2323:
                   2324: @deftypefun mp_limb_t mpn_gcd_1 (const mp_limb_t * @var{src1_ptr}, mp_size_t @var{src1_size}, mp_limb_t @var{src2_limb})
                   2325: Return the greatest common divisor of @{@var{src1_ptr}, @var{src1_size}@}
                   2326: and @var{src2_limb}, where @var{src2_limb} (as well as @var{src1_size})
                   2327: must be different from 0.
                   2328: @end deftypefun
                   2329:
                   2330: @deftypefun mp_size_t mpn_gcdext (mp_limb_t * @var{r1p}, mp_limb_t * @var{r2p}, mp_limb_t * @var{s1p}, mp_size_t @var{s1size}, mp_limb_t * @var{s2p}, mp_size_t @var{s2size})
                   2331: Puts at @var{r1p} the greatest common divisor of @{@var{s1p}, @var{s1size}@}
                   2332: and @{@var{s2p}, @var{s2size}@}.  The first cofactor is written at
                   2333: @var{r2p}.  Both source operands are destroyed by the operation.  The size
                   2334: in limbs of the greatest common divisor is returned.
                   2335:
                   2336: @strong{This interface is preliminary.  It might change incompatibly in
                   2337: future revisions.}
                   2338: @end deftypefun
                   2339:
                   2340: @deftypefun mp_size_t mpn_sqrtrem (mp_limb_t * @var{r1p}, mp_limb_t * @var{r2p}, const mp_limb_t * @var{sp}, mp_size_t @var{size})
                   2341: Compute the square root of @{@var{sp}, @var{size}@} and put the result at
                   2342: @var{r1p}.  Write the remainder at @var{r2p}, unless @var{r2p} is NULL.
                   2343:
                   2344: Return the size of the remainder, whether @var{r2p} was NULL or non-NULL.
                   2345: Iff the operand was a perfect square, the return value will be 0.
                   2346:
                   2347: The areas at @var{r1p} and @var{sp} have to be distinct.  The areas at
                   2348: @var{r2p} and @var{sp} have to be identical or completely separate, not
                   2349: partially overlapping.
                   2350:
                   2351: @ifinfo
                   2352: The area at @var{r1p} needs to have space for ceil(@var{size}/2) limbs.
                   2353: @end ifinfo
                   2354: @iftex
                   2355: @tex
                   2356: The area at @var{r1p} needs to have space for $\lceil@var{size}/2\rceil$ limbs.
                   2357: @end tex
                   2358: @end iftex
                   2359: The area at @var{r2p} needs to be @var{size} limbs large.
                   2360:
                   2361: @strong{This interface is preliminary.  It might change incompatibly in
                   2362: future revisions.}
                   2363: @end deftypefun
                   2364:
                   2365: @deftypefun mp_size_t mpn_get_str (unsigned char *@var{str}, int @var{base}, mp_limb_t * @var{s1p}, mp_size_t @var{s1size})
                   2366: Convert @{@var{s1p}, @var{s1size}@} to a raw unsigned char array in base
                   2367: @var{base}.  The string is not in ASCII; to convert it to printable format,
                   2368: add the ASCII codes for @samp{0} or @samp{A}, depending on the base and
                   2369: range.  There may be leading zeros in the string.
                   2370:
                   2371: The area at @var{s1p} is clobbered.
                   2372:
                   2373: Return the number of characters in @var{str}.
                   2374:
                   2375: The area at @var{str} has to have space for the largest possible number
                   2376: represented by a @var{s1size} long limb array, plus one extra character.
                   2377: @end deftypefun
                   2378:
                   2379: @deftypefun mp_size_t mpn_set_str (mp_limb_t * @var{r1p}, const char *@var{str}, size_t {strsize}, int @var{base})
                   2380: Convert the raw unsigned char array at @var{str} of length @var{strsize} to
                   2381: a limb array @{@var{s1p}, @var{s1size}@}.  The base of @var{str} is
                   2382: @var{base}.
                   2383:
                   2384: Return the number of limbs stored in @var{r1p}.
                   2385: @end deftypefun
                   2386:
                   2387: @deftypefun {unsigned long int} mpn_scan0 (const mp_limb_t * @var{s1p}, unsigned long int @var{bit})
                   2388: Scan @var{s1p} from bit position @var{bit} for the next clear bit.
                   2389:
                   2390: It is required that there be a clear bit within the area at @var{s1p} at or
                   2391: beyond bit position @var{bit}, so that the function has something to return.
                   2392:
                   2393: @strong{This interface is preliminary.  It might change incompatibly in
                   2394: future revisions.}
                   2395: @end deftypefun
                   2396:
                   2397: @deftypefun {unsigned long int} mpn_scan1 (const mp_limb_t * @var{s1p}, unsigned long int @var{bit})
                   2398: Scan @var{s1p} from bit position @var{bit} for the next set bit.
                   2399:
                   2400: It is required that there be a set bit within the area at @var{s1p} at or
                   2401: beyond bit position @var{bit}, so that the function has something to return.
                   2402:
                   2403: @strong{This interface is preliminary.  It might change incompatibly in
                   2404: future revisions.}
                   2405: @end deftypefun
                   2406:
                   2407: @deftypefun void mpn_random2 (mp_limb_t * @var{r1p}, mp_size_t @var{r1size})
                   2408: Generate a random number of length @var{r1size} with long strings of zeros
                   2409: and ones in the binary representation, and store it at @var{r1p}.
                   2410:
                   2411: The generated random numbers are intended for testing the correctness of the
                   2412: implementation of the @code{mpn} routines.
                   2413: @end deftypefun
                   2414:
                   2415: @deftypefun {unsigned long int} mpn_popcount (const mp_limb_t * @var{s1p}, unsigned long int @var{size})
                   2416: Count the number of set bits in @{@var{s1p}, @var{size}@}.
                   2417: @end deftypefun
                   2418:
                   2419: @deftypefun {unsigned long int} mpn_hamdist (const mp_limb_t * @var{s1p}, const mp_limb_t * @var{s2p}, unsigned long int @var{size})
                   2420: Compute the hamming distance between @{@var{s1p}, @var{size}@} and
                   2421: @{@var{s2p}, @var{size}@}.
                   2422: @end deftypefun
                   2423:
                   2424: @deftypefun int mpn_perfect_square_p (const mp_limb_t * @var{s1p}, mp_size_t @var{size})
                   2425: Return non-zero iff @{@var{s1p}, @var{size}@} is a perfect square.
                   2426: @end deftypefun
                   2427:
                   2428:
                   2429: @node BSD Compatible Functions, Custom Allocation, Low-level Functions, Top
                   2430: @comment  node-name,  next,  previous,  up
                   2431: @chapter Berkeley MP Compatible Functions
                   2432: @cindex BSD MP compatible functions
                   2433:
                   2434: These functions are intended to be fully compatible with the Berkeley MP
                   2435: library which is available on many BSD derived U*ix systems.
                   2436:
                   2437: The original Berkeley MP library has a usage restriction: you cannot use the
                   2438: same variable as both source and destination in a single function call.  The
                   2439: compatible functions in GNU MP do not share this restriction---inputs and
                   2440: outputs may overlap.
                   2441:
                   2442: It is not recommended that new programs are written using these functions.
                   2443: Apart from the incomplete set of functions, the interface for initializing
                   2444: @code{MINT} objects is more error prone, and the @code{pow} function collides
                   2445: with @code{pow} in @file{libm.a}.
                   2446:
                   2447: @cindex @file{mp.h}
                   2448: Include the header @file{mp.h} to get the definition of the necessary types
                   2449: and functions.  If you are on a BSD derived system, make sure to include GNU
                   2450: @file{mp.h} if you are going to link the GNU @file{libmp.a} to you program.
                   2451: This means that you probably need to give the -I<dir> option to the compiler,
                   2452: where <dir> is the directory where you have GNU @file{mp.h}.
                   2453:
                   2454: @deftypefun {MINT *} itom (signed short int @var{initial_value})
                   2455: Allocate an integer consisting of a @code{MINT} object and dynamic limb space.
                   2456: Initialize the integer to @var{initial_value}.  Return a pointer to the
                   2457: @code{MINT} object.
                   2458: @end deftypefun
                   2459:
                   2460: @deftypefun {MINT *} xtom (char *@var{initial_value})
                   2461: Allocate an integer consisting of a @code{MINT} object and dynamic limb space.
                   2462: Initialize the integer from @var{initial_value}, a hexadecimal, '\0'-terminate
                   2463: C string.  Return a pointer to the @code{MINT} object.
                   2464: @end deftypefun
                   2465:
                   2466: @deftypefun void move (MINT *@var{src}, MINT *@var{dest})
                   2467: Set @var{dest} to @var{src} by copying.  Both variables must be previously
                   2468: initialized.
                   2469: @end deftypefun
                   2470:
                   2471: @deftypefun void madd (MINT *@var{src_1}, MINT *@var{src_2}, MINT *@var{destination})
                   2472: Add @var{src_1} and @var{src_2} and put the sum in @var{destination}.
                   2473: @end deftypefun
                   2474:
                   2475: @deftypefun void msub (MINT *@var{src_1}, MINT *@var{src_2}, MINT *@var{destination})
                   2476: Subtract @var{src_2} from @var{src_1} and put the difference in
                   2477: @var{destination}.
                   2478: @end deftypefun
                   2479:
                   2480: @deftypefun void mult (MINT *@var{src_1}, MINT *@var{src_2}, MINT *@var{destination})
                   2481: Multiply @var{src_1} and @var{src_2} and put the product in
                   2482: @var{destination}.
                   2483: @end deftypefun
                   2484:
                   2485: @deftypefun void mdiv (MINT *@var{dividend}, MINT *@var{divisor}, MINT *@var{quotient}, MINT *@var{remainder})
                   2486: @deftypefunx void sdiv (MINT *@var{dividend}, signed short int @var{divisor}, MINT *@var{quotient}, signed short int *@var{remainder})
                   2487: Set @var{quotient} to @var{dividend}/@var{divisor}, and @var{remainder} to
                   2488: @var{dividend} mod @var{divisor}.  The quotient is rounded towards zero; the
                   2489: remainder has the same sign as the dividend unless it is zero.
                   2490:
                   2491: Some implementations of these functions work differently---or not at all---for
                   2492: negative arguments.
                   2493: @end deftypefun
                   2494:
                   2495: @deftypefun void msqrt (MINT *@var{operand}, MINT *@var{root}, MINT *@var{remainder})
                   2496: @ifinfo
                   2497: Set @var{root} to the truncated integer part of the square root of
                   2498: @var{operand}.  Set @var{remainder} to
                   2499: @var{operand}@minus{}@var{root}*@var{root},
                   2500: @end ifinfo
                   2501: @iftex
                   2502: @tex
                   2503: Set @var{root} to $\lfloor\sqrt{@var{operand}}\rfloor$, like
                   2504: @code{mpz_sqrt}.  Set @var{remainder} to $(operand - root^2)$,
                   2505: @end tex
                   2506: @end iftex
                   2507: (i.e., zero if @var{operand} is a perfect square).
                   2508:
                   2509: If @var{root} and @var{remainder} are the same variable, the results are
                   2510: undefined.
                   2511: @end deftypefun
                   2512:
                   2513: @deftypefun void pow (MINT *@var{base}, MINT *@var{exp}, MINT *@var{mod}, MINT *@var{dest})
                   2514: Set @var{dest} to (@var{base} raised to @var{exp}) modulo @var{mod}.
                   2515: @end deftypefun
                   2516:
                   2517: @deftypefun void rpow (MINT *@var{base}, signed short int @var{exp}, MINT *@var{dest})
                   2518: Set @var{dest} to @var{base} raised to @var{exp}.
                   2519: @end deftypefun
                   2520:
                   2521: @deftypefun void gcd (MINT *@var{operand1}, MINT *@var{operand2}, MINT *@var{res})
                   2522: Set @var{res} to the greatest common divisor of @var{operand1} and
                   2523: @var{operand2}.
                   2524: @end deftypefun
                   2525:
                   2526: @deftypefun int mcmp (MINT *@var{operand1}, MINT *@var{operand2})
                   2527: Compare @var{operand1} and @var{operand2}.  Return a positive value if
                   2528: @var{operand1} > @var{operand2}, zero if @var{operand1} =
                   2529: @var{operand2}, and a negative value if @var{operand1} < @var{operand2}.
                   2530: @end deftypefun
                   2531:
                   2532: @deftypefun void min (MINT *@var{dest})
                   2533: Input a decimal string from @code{stdin}, and put the read integer in
                   2534: @var{dest}.  SPC and TAB are allowed in the number string, and are ignored.
                   2535: @end deftypefun
                   2536:
                   2537: @deftypefun void mout (MINT *@var{src})
                   2538: Output @var{src} to @code{stdout}, as a decimal string.  Also output a newline.
                   2539: @end deftypefun
                   2540:
                   2541: @deftypefun {char *} mtox (MINT *@var{operand})
                   2542: Convert @var{operand} to a hexadecimal string, and return a pointer to the
                   2543: string.  The returned string is allocated using the default memory allocation
                   2544: function, @code{malloc} by default.
                   2545: @end deftypefun
                   2546:
                   2547: @deftypefun void mfree (MINT *@var{operand})
                   2548: De-allocate, the space used by @var{operand}.  @strong{This function should
                   2549: only be passed a value returned by @code{itom} or @code{xtom}.}
                   2550: @end deftypefun
                   2551:
                   2552: @node Custom Allocation, Contributors, BSD Compatible Functions, Top
                   2553: @comment  node-name,  next,  previous,  up
                   2554: @chapter Custom Allocation
                   2555:
                   2556: By default, the MP functions use @code{malloc}, @code{realloc}, and
                   2557: @code{free} for memory allocation.  If @code{malloc} or @code{realloc} fails,
                   2558: the MP library terminates execution after printing a fatal error message to
                   2559: standard error.
                   2560:
                   2561: For some applications, you may wish to allocate memory in other ways, or you
                   2562: may not want to have a fatal error when there is no more memory available.  To
                   2563: accomplish this, you can specify alternative memory allocation functions.
                   2564:
                   2565: @deftypefun void mp_set_memory_functions (@* void *(*@var{alloc_func_ptr}) (size_t), @* void *(*@var{realloc_func_ptr}) (void *, size_t, size_t), @* void (*@var{free_func_ptr}) (void *, size_t))
                   2566: Replace the current allocation functions from the arguments.  If an argument
                   2567: is NULL, the corresponding default function is retained.
                   2568:
                   2569: @strong{Make sure to call this function in such a way that there are no active
                   2570: MP objects that were allocated using the previously active allocation
                   2571: function!  Usually, that means that you have to call this function before any
                   2572: other MP function.}
                   2573: @end deftypefun
                   2574:
                   2575: The functions you supply should fit the following declarations:
                   2576:
                   2577: @deftypefun {void *} allocate_function (size_t @var{alloc_size})
                   2578: This function should return a pointer to newly allocated space with at least
                   2579: @var{alloc_size} storage units.
                   2580: @end deftypefun
                   2581:
                   2582: @deftypefun {void *} reallocate_function (void *@var{ptr}, size_t @var{old_size}, size_t @var{new_size})
                   2583: This function should return a pointer to newly allocated space of at least
                   2584: @var{new_size} storage units, after copying at least the first @var{old_size}
                   2585: storage units from @var{ptr}.  It should also de-allocate the space at
                   2586: @var{ptr}.
                   2587:
                   2588: You can assume that the space at @var{ptr} was formerly returned from
                   2589: @code{allocate_function} or @code{reallocate_function}, for a request for
                   2590: @var{old_size} storage units.
                   2591: @end deftypefun
                   2592:
                   2593: @deftypefun void deallocate_function (void *@var{ptr}, size_t @var{size})
                   2594: De-allocate the space pointed to by @var{ptr}.
                   2595:
                   2596: You can assume that the space at @var{ptr} was formerly returned from
                   2597: @code{allocate_function} or @code{reallocate_function}, for a request for
                   2598: @var{size} storage units.
                   2599: @end deftypefun
                   2600:
                   2601: (A @dfn{storage unit} is the unit in which the @code{sizeof} operator returns
                   2602: the size of an object, normally an 8 bit byte.)
                   2603:
                   2604:
                   2605: @node Contributors, References, Custom Allocation, Top
                   2606: @comment  node-name,  next,  previous,  up
                   2607: @unnumbered Contributors
                   2608:
                   2609: I would like to thank Gunnar Sjoedin and Hans Riesel for their help with
                   2610: mathematical problems, Richard Stallman for his help with design issues and
                   2611: for revising the first version of this manual, Brian Beuning and Doug Lea for
                   2612: their testing of early versions of the library.
                   2613:
                   2614: John Amanatides of York University in Canada contributed the function
                   2615: @code{mpz_probab_prime_p}.
                   2616:
                   2617: Paul Zimmermann of Inria sparked the development of GMP 2, with his
                   2618: comparisons between bignum packages.
                   2619:
                   2620: Ken Weber (Kent State University, Universidade Federal do Rio Grande do Sul)
                   2621: contributed @code{mpz_gcd}, @code{mpz_divexact}, @code{mpn_gcd}, and
                   2622: @code{mpn_bdivmod}, partially supported by CNPq (Brazil) grant 301314194-2.
                   2623:
                   2624: Per Bothner of Cygnus Support helped to set up MP to use Cygnus' configure.
                   2625: He has also made valuable suggestions and tested numerous intermediary
                   2626: releases.
                   2627:
                   2628: Joachim Hollman was involved in the design of the @code{mpf} interface, and in
                   2629: the @code{mpz} design revisions for version 2.
                   2630:
                   2631: Bennet Yee contributed the functions @code{mpz_jacobi} and
                   2632: @code{mpz_legendre}.
                   2633:
                   2634: Andreas Schwab contributed the files @file{mpn/m68k/lshift.S} and
                   2635: @file{mpn/m68k/rshift.S}.
                   2636:
                   2637: The development of floating point functions of GNU MP 2, were supported in
                   2638: part by the ESPRIT-BRA (Basic Research Activities) 6846 project POSSO
                   2639: (POlynomial System SOlving).
                   2640:
                   2641: GNU MP 2 was finished and released by TMG Datakonsult, Sodermannagatan 5, 116
                   2642: 23 STOCKHOLM, SWEDEN, in cooperation with the IDA Center for Computing
                   2643: Sciences, USA.
                   2644:
                   2645:
                   2646: @node References, , Contributors, Top
                   2647: @comment  node-name,  next,  previous,  up
                   2648: @unnumbered References
                   2649:
                   2650: @itemize @bullet
                   2651:
                   2652: @item
                   2653: Donald E. Knuth, "The Art of Computer Programming", vol 2,
                   2654: "Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981.
                   2655:
                   2656: @item
                   2657: John D. Lipson, "Elements of Algebra and Algebraic Computing",
                   2658: The Benjamin Cummings Publishing Company Inc, 1981.
                   2659:
                   2660: @item
                   2661: Richard M. Stallman, "Using and Porting GCC", Free Software Foundation,
                   2662: 1995.
                   2663:
                   2664: @item
                   2665: Peter L. Montgomery, "Modular Multiplication Without Trial Division", in
                   2666: Mathematics of Computation, volume 44, number 170, April 1985.
                   2667:
                   2668: @item
                   2669: Torbjorn Granlund and Peter L. Montgomery, "Division by Invariant
                   2670: Integers using Multiplication", in Proceedings of the SIGPLAN
                   2671: PLDI'94 Conference, June 1994.
                   2672:
                   2673: @item
                   2674: Tudor Jebelean,
                   2675: "An algorithm for exact division",
                   2676: Journal of Symbolic Computation,
                   2677: v. 15, 1993, pp. 169-180.
                   2678:
                   2679: @item
                   2680: Kenneth Weber, "The accelerated integer GCD algorithm",
                   2681: ACM Transactions on Mathematical Software,
                   2682: v. 21 (March), 1995, pp. 111-122.
                   2683: @end itemize
                   2684:
                   2685: @node Concept Index, , , Top
                   2686: @comment  node-name,  next,  previous,  up
                   2687: @unnumbered Concept Index
                   2688: @printindex cp
                   2689:
                   2690: @node Function Index, , , Top
                   2691: @comment  node-name,  next,  previous,  up
                   2692: @unnumbered Function and Type Index
                   2693: @printindex fn
                   2694:
                   2695:
                   2696: @contents
                   2697: @bye

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>