=================================================================== RCS file: /home/cvs/OpenXM_contrib/gmp/Attic/gmp.texi,v retrieving revision 1.1.1.1 retrieving revision 1.1.1.2 diff -u -p -r1.1.1.1 -r1.1.1.2 --- OpenXM_contrib/gmp/Attic/gmp.texi 2000/01/10 15:35:21 1.1.1.1 +++ OpenXM_contrib/gmp/Attic/gmp.texi 2000/09/09 14:12:16 1.1.1.2 @@ -1,20 +1,18 @@ \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename gmp.info -@settitle GNU MP 2.0.2 +@include version.texi +@settitle GNU MP @value{VERSION} @synindex tp fn @iftex @afourpaper @end iftex @comment %**end of header -@ifinfo -@format -START-INFO-DIR-ENTRY -* gmp: (gmp.info). GNU Multiple Precision Arithmetic Library. -END-INFO-DIR-ENTRY -@end format -@end ifinfo +@dircategory GNU libraries +@direntry +* gmp: (gmp). GNU Multiple Precision Arithmetic Library. +@end direntry @c smallbook @@ -22,17 +20,19 @@ END-INFO-DIR-ENTRY @finalout @end iftex -@c Note: the edition number is listed in *three* places; please update -@c all three. Also, update the month and year where appropriate. +@c Texinfo version 4 or up will be needed to process this into .info files. +@c +@c The edition number is in three places and the month/year in one, all +@c taken from version.texi. version.texi is created when you configure with +@c --enable-maintainer-mode, and is included in a distribution made with +@c "make dist". -@c ==> Update edition number for settitle and subtitle, and in the -@c ==> following paragraph; update date, too. - -@ifinfo +@ifnottex This file documents GNU MP, a library for arbitrary-precision arithmetic. -Copyright (C) 1991, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. +Copyright (C) 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 Free +Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -43,8 +43,8 @@ Permission is granted to process this file through TeX results, provided the printed document carries copying permission notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual). - @end ignore + Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission @@ -54,7 +54,7 @@ Permission is granted to copy and distribute translati into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. -@end ifinfo +@end ifnottex @setchapternewpage on @titlepage @@ -62,10 +62,11 @@ by the Foundation. @title GNU MP @subtitle The GNU Multiple Precision Arithmetic Library -@subtitle Edition 2.0.2 -@subtitle June 1996 +@subtitle Edition @value{EDITION} +@subtitle @value{UPDATED} -@author by Torbj@"orn Granlund, TMG Datakonsult +@author by Torbj@"orn Granlund, Swox AB +@email{tege@@swox.com} @c Include the Distribution inside the titlepage so @c that headings are turned off. @@ -78,7 +79,8 @@ by the Foundation. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1991, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. +Copyright @copyright{} 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 +Free Software Foundation, Inc. @sp 2 @@ -102,36 +104,37 @@ by the Foundation. @end titlepage @headings double -@ifinfo +@ifnottex @node Top, Copying, (dir), (dir) @top GNU MP This manual documents how to install and use the GNU multiple precision -arithmetic library, version 2.0.2. +arithmetic library, version @value{VERSION}. -@end ifinfo +@end ifnottex @menu -* Copying:: GMP Copying Conditions (LGPL). -* Introduction to MP:: Brief introduction to GNU MP. -* Installing MP:: How to configure and compile the MP library. -* MP Basics:: What every MP user should now. -* Reporting Bugs:: How to usefully report bugs. -* Integer Functions:: Functions for arithmetic on signed integers. -* Rational Number Functions:: Functions for arithmetic on rational numbers. -* Floating-point Functions:: Functions for arithmetic on floats. -* Low-level Functions:: Fast functions for natural numbers. -* BSD Compatible Functions:: All functions found in BSD MP. -* Custom Allocation:: How to customize the internal allocation. +* Copying:: GMP Copying Conditions (LGPL). +* Introduction to GMP:: Brief introduction to GNU MP. +* Installing GMP:: How to configure and compile the GMP library. +* GMP Basics:: What every GMP user should now. +* Reporting Bugs:: How to usefully report bugs. +* Integer Functions:: Functions for arithmetic on signed integers. +* Rational Number Functions:: Functions for arithmetic on rational numbers. +* Floating-point Functions:: Functions for arithmetic on floats. +* Low-level Functions:: Fast functions for natural numbers. +* Random Number Functions:: Functions for generating random numbers. +* BSD Compatible Functions:: All functions found in BSD MP. +* Custom Allocation:: How to customize the internal allocation. -* Contributors:: -* References:: +* Contributors:: Who brings your this library? +* References:: Some useful papers and books to read. * Concept Index:: * Function Index:: @end menu -@node Copying, Introduction to MP, Top, Top +@node Copying, Introduction to GMP, Top, Top @comment node-name, next, previous, up @unnumbered GNU MP Copying Conditions @cindex Copying conditions @@ -165,209 +168,629 @@ will not reflect on our reputation.@refill The precise conditions of the license for the GNU MP library are found in the Library General Public License that accompany the source code.@refill -@node Introduction to MP, Installing MP, Copying, Top + +@node Introduction to GMP, Installing GMP, Copying, Top @comment node-name, next, previous, up @chapter Introduction to GNU MP +@cindex Introduction - GNU MP is a portable library written in C for arbitrary precision arithmetic on integers, rational numbers, and floating-point numbers. It aims to provide the fastest possible arithmetic for all applications that need higher precision than is directly supported by the basic C types. Many applications use just a few hundred bits of precision; but some -applications may need thousands or even millions of bits. MP is designed to +applications may need thousands or even millions of bits. GMP is designed to give good performance for both, by choosing algorithms based on the sizes of the operands, and by carefully keeping the overhead at a minimum. -The speed of MP is achieved by using fullwords as the basic arithmetic type, +The speed of GMP is achieved by using fullwords as the basic arithmetic type, by using sophisticated algorithms, by including carefully optimized assembly code for the most common inner loops for many different CPUs, and by a general emphasis on speed (as opposed to simplicity or elegance). -There is carefully optimized assembly code for these CPUs: DEC Alpha, Amd -29000, HPPA 1.0 and 1.1, Intel Pentium and generic x86, Intel i960, Motorola -MC68000, MC68020, MC88100, and MC88110, Motorola/IBM PowerPC, National -NS32000, IBM POWER, MIPS R3000, R4000, SPARCv7, SuperSPARC, generic SPARCv8, -and DEC VAX. Some optimizations also for ARM, Clipper, IBM ROMP (RT), and -Pyramid AP/XP. +There is carefully optimized assembly code for these CPUs: +@cindex CPUs supported +ARM, +DEC Alpha 21064, 21164, and 21264, +AMD 29000, +AMD K6 and Athlon, +Hitachi SuperH and SH-2, +HPPA 1.0, 1.1 and 2.0, +Intel Pentium, Pentium Pro/Pentium II, generic x86, +Intel i960, +Motorola MC68000, MC68020, MC88100, and MC88110, +Motorola/IBM PowerPC 32 and 64, +National NS32000, +IBM POWER, +MIPS R3000, R4000, +SPARCv7, SuperSPARC, generic SPARCv8, UltraSPARC, +DEC VAX, +and Zilog Z8000. +Some optimizations also for Clipper, IBM ROMP (RT), and Pyramid AP/XP. -This version of MP is released under a more liberal license than previous -versions. It is now permitted to link MP to non-free programs, as long as MP -source code is provided when distributing the non-free program. +@cindex Mailing list +There is a mailing list for GMP users. To join it, send a mail to +@email{gmp-request@@swox.com} with the word @samp{subscribe} in the message +@strong{body} (not in the subject line). +@cindex Home page +@cindex Web page +For up-to-date information on GMP, please see the GMP Home Pages at +@uref{http://www.swox.com/gmp/}. + @section How to use this Manual +@cindex About this manual -Everyone should read @ref{MP Basics}. If you need to install the library -yourself, you need to read @ref{Installing MP}, too. +Everyone should read @ref{GMP Basics}. If you need to install the library +yourself, you need to read @ref{Installing GMP}, too. The rest of the manual can be used for later reference, although it is probably a good idea to glance through it. -@node Installing MP, MP Basics, Introduction to MP, Top +@node Installing GMP, GMP Basics, Introduction to GMP, Top @comment node-name, next, previous, up -@chapter Installing MP -@cindex Installation +@chapter Installing GMP +@cindex Installing GMP +@cindex Configuring GMP -To build MP, you first have to configure it for your CPU and operating system. -You need a C compiler, preferably GCC, but any reasonable compiler should -work. And you need a standard Unix @samp{make} program, plus some other -standard Unix utility programs. +@noindent +GMP has an autoconf/automake/libtool based configuration system. On a +Unix-like system a basic build can be done with -(If you're on an MS-DOS machine, your can build MP using @file{make.bat}. It -requires that djgpp is installed. It does not require configuration, nor is -@samp{make} needed; @file{make.bat} both configures and builds the library.) +@example +./configure +make +@end example -Here are the steps needed to install the library on Unix systems: +@noindent +Some self-tests can be run with -@enumerate -@item -In most cases, @samp{./configure --target=cpu-vendor-os}, should work both for -native and cross-compilation. If you get error messages, your machine might -not be supported. +@example +make check +@end example -If you want to compile in a separate object directory, cd to that directory, -and prefix the configure command with the path to the MP source directory. -Not all @samp{make} programs have the necessary features to support this. In -particular, SunOS and Slowaris @samp{make} have bugs that makes them unable to -build from a separate object directory. Use GNU @samp{make} instead. +@noindent +And you can install (under @file{/usr/local} by default) with -In addition to the standard cpu-vendor-os tuples, MP recognizes sparc8 and -supersparc as valid CPU names. Specifying these CPU names for relevant -systems will improve performance significantly. +@example +make install +@end example -In general, if you want a library that runs as fast as possible, you should -make sure you configure MP for the exact CPU type your system uses. +@noindent +If you experience problems, please report them to @email{bug-gmp@@gnu.org}. +(@xref{Reporting Bugs}, for information on what to include in useful bug +reports.) -If you have @code{gcc} in your @code{PATH}, it will be used by default. To -override this, pass @samp{-with-gcc=no} to @file{configure}. +@menu +* Build Options:: +* ABI and ISA:: +* Notes for Package Builds:: +* Notes for Particular Systems:: +* Known Build Problems:: +@end menu -@item -@samp{make} -This will compile MP, and create a library archive file @file{libgmp.a} in the -working directory. +@node Build Options, ABI and ISA, Installing GMP, Installing GMP +@section Build Options +@cindex Build options -@item -@samp{make check} +@noindent +All the usual autoconf configure options are available, run @samp{./configure +--help} for a summary. -This will make sure MP was built correctly. If you get error messages, please -report this to @samp{bug-gmp@@prep.ai.mit.edu}. (@xref{Reporting Bugs}, for -information on what to include in useful bug reports.) +@table @asis +@item Non-Unix Systems -@item -@samp{make install} +@samp{configure} needs various Unix-like tools installed. On an MS-DOS system +cygwin or djgpp should work. It might be possible to build without the help +of @samp{configure}, certainly all the code is there, but unfortunately you'll +be on your own. -This will copy the file @file{gmp.h} and @file{libgmp.a}, as well as the info -files, to @file{/usr/local} (or if you passed the @samp{--prefix} option to -@file{configure}, to the directory given as argument to @samp{--prefix}). -@end enumerate +@item Object Directory -@noindent -If you wish to build and install the BSD MP compatible functions, use -@samp{make libmp.a} and @samp{make install-bsdmp}. +To compile in a separate object directory, @command{cd} to that directory, and +prefix the configure command with the path to the GMP source directory. For +example @samp{../src/gmp/configure}. Not all @samp{make} programs have the +necessary features (@code{VPATH}) to support this. In particular, SunOS and +Slowaris @command{make} have bugs that make them unable to build from a +separate object directory. Use GNU @command{make} instead. -There are some other useful make targets: +@item @option{--disable-shared}, @option{--disable-static} +By default both shared and static libraries are built (where possible), but +one or other can be disabled. Shared libraries are very slightly slower, +having a small cost on each function call, but result in smaller executables +and permit code sharing between separate running processes. + +@item @option{--target=CPU-VENDOR-OS} + +The build target can be specified in the usual way, for either native or cross +compilation. + +If @option{--target} isn't given, @samp{./configure} builds for the host +system as determined by @samp{./config.guess}. On some systems this can't +distinguish between different CPUs in a family, and you should check the +guess. Running @samp{./config.guess} on the target system will also show the +relevant @samp{VENDOR-OS}, if you don't already know what it should be. + +In general, if you want a library that runs as fast as possible, you should +configure GMP for the exact CPU type your system uses. However, this may mean +the binaries won't run on older members of the family, and might run slower on +other members, older or newer. The best idea is always to build GMP for the +exact machine type you intend to run it on. + +The following CPU targets have specific assembly code support. See +@file{configure.in} for which @file{mpn} subdirectories get used by each. + @itemize @bullet -@item -@samp{doc} -Create a DVI version of the manual, in @file{gmp.dvi} and a set of info files, -in @file{gmp.info}, @file{gmp.info-1}, @file{gmp.info-2}, etc. +@c Keep this formatting, it's easy to read and it can be grepped to +@c automatically test that targets listed get through ./config.sub @item -@samp{ps} +Alpha: +@samp{alpha}, +@samp{alphaev5}, +@samp{alphaev6} -Create a Postscript version of the manual, in @file{gmp.ps}. +@item +Hitachi: +@samp{sh}, +@samp{sh2} @item -@samp{html} +HPPA: +@samp{hppa1.0}, +@samp{hppa1.1}, +@samp{hppa2.0}, +@samp{hppa2.0w} -Create a HTML version of the manual, in @file{gmp.html}. +@item +MIPS: +@samp{mips}, +@samp{mips3}, @item -@samp{clean} +Motorola: +@samp{m68000}, +@samp{m68k}, +@samp{m88k}, +@samp{m88110} -Delete all object files and archive files, but not the configuration files. +@item +POWER: +@samp{power1}, +@samp{power2}, +@samp{power2sc}, +@samp{powerpc}, +@samp{powerpc64} @item -@samp{distclean} +SPARC: +@samp{sparc}, +@samp{sparcv8}, +@samp{microsparc}, +@samp{supersparc}, +@samp{sparcv9}, +@samp{ultrasparc}, +@samp{sparc64} -Delete all files not included in the distribution. - @item -@samp{uninstall} +80x86 family: +@samp{i386}, +@samp{i486}, +@samp{i586}, +@samp{pentium}, +@samp{pentiummmx}, +@samp{pentiumpro}, +@samp{pentium2}, +@samp{pentium3}, +@samp{k6}, +@samp{k62}, +@samp{k63}, +@samp{athlon} -Delete all files copied by @samp{make install}. +@item +Other: +@samp{a29k}, +@samp{arm}, +@samp{clipper}, +@samp{i960}, +@samp{ns32k}, +@samp{pyramid}, +@samp{vax}, +@samp{z8k} @end itemize +CPUs not listed use generic C code. If some of the assembly code causes +problems, the generic C code can be selected with CPU @samp{none}. -@section Known Build Problems +@item @option{CC}, @option{CFLAGS} -GCC 2.7.2 (as well as 2.6.3) for the RS/6000 and PowerPC can not be used to -compile MP, due to a bug in GCC. If you want to use GCC for these machines, -you need to apply the patch below to GCC, or use a later version of the -compiler. +The C compiler used is chosen from among some likely candidates, with GCC +normally preferred if it's present. The usual @samp{CC=whatever} can be +passed to @samp{./configure} to choose something different. -If you are on a Sequent Symmetry, use the GNU assembler instead of the -system's assembler, since the latter has serious bugs. +For some configurations specific compiler flags are set based on the target +CPU and compiler, for others @samp{CFLAGS="-whatever"} can be used to +set the best flags. -The system compiler on NeXT is a massacred and old gcc, even if the compiler -calls itself @file{cc}. This compiler cannot be used to build MP. You need -to get a real gcc, and install that before you compile MP. (NeXT might have -fixed this in newer releases of their system.) +If @samp{CC} is set then @samp{CFLAGS} must also be set. This applies even if +@samp{CC} is merely one of the choices GMP would make itself. This may change +in a future release. -The system C compiler under SunOS 4 has a bug that makes it miscompile -mpq/get_d.c. This will make @samp{make check} fail. +@item @option{--disable-alloca} +@cindex Stack overflow segfaults +@cindex @code{alloca} -Please report other problems to @samp{bug-gmp@@prep.ai.mit.edu}. -@xref{Reporting Bugs}. +By default, GMP allocates temporary workspace using @code{alloca} if that +function is available, or @code{malloc} if not. If you're working with large +numbers and @code{alloca} overflows the available stack space, you can build +with @option{--disable-alloca} to use @code{malloc} instead. @code{malloc} +will probably be slightly slower than @code{alloca}. +When not using @code{alloca}, it's actually the allocation function +selected with @code{mp_set_memory_functions} that's used, this being +@code{malloc} by default. @xref{Custom Allocation}. -Patch to apply to GCC 2.6.3 and 2.7.2: +Depending on your system, the only indication of stack overflow might be a +segmentation violation. It might be possible to increase available stack +space with @command{limit}, @command{ulimit} or @code{setrlimit}, or under +DJGPP with @command{stubedit} or @code{_stklen}. +@item @option{--enable-fft} + +By default multiplications are done using Karatsuba and 3-way Toom-Cook +algorithms, but a Fermat FFT can be enabled, for use on large to very large +operands. Currently the FFT is recommended only for knowledgeable users who +check the algorithm thresholds for their CPU. + +@item @option{--enable-mpbsd} + +The Berkeley MP compatibility library (@file{libmp.a}) and header file +(@file{mp.h}) are built and installed only if @option{--enable-mpbsd} is used. +@xref{BSD Compatible Functions}. + +@item @option{MPN_PATH} + +Various assembler versions of mpn subroutines are provided, and, for a given +CPU target, a search is made though a path to choose a version of each. For +example @samp{sparcv8} has path @samp{"sparc32/v8 sparc32 generic"}, which +means it looks first for v8 code, falls back on plain sparc32, and finally +falls back on generic C. Knowledgeable users with special requirements can +specify a path with @samp{MPN_PATH="dir list"}. This will normally be +unnecessary because all sensible paths should be available under one or other +CPU target. + +@item Demonstration Programs +@cindex Demonstration programs +@cindex Example programs + +The @file{demos} subdirectory has some sample programs using GMP. These +aren't built or installed, but there's a @file{Makefile} with rules for them. +For instance, @samp{make pexpr} and then @samp{./pexpr 68^975+10}. + +@item Documentation + +The document you're now reading is @file{gmp.texi}. The usual automake +targets are available to make @file{gmp.ps} and/or @file{gmp.dvi}. Some +supplementary notes can be found in the @file{doc} subdirectory. +@end table + + +@need 2000 +@node ABI and ISA, Notes for Package Builds, Build Options, Installing GMP +@section ABI and ISA +@cindex ABI +@cindex ISA + +ABI (Application Binary Interface) refers to the calling conventions between +functions, meaning what registers are used and what sizes the various C data +types are. ISA (Instruction Set Architecture) refers to the instructions and +registers a CPU has available. + +Some 64-bit ISA CPUs have both a 64-bit ABI and a 32-bit ABI defined, the +latter for compatibility with older CPUs in the family. GMP chooses the best +ABI available for a given target system, and this generally gives +significantly greater speed. + +The burden is on application programs and cooperating libraries to ensure they +match the ABI chosen by GMP. Fortunately this presents a difficulty only on a +few systems, and if you have one of them then the performance gains are enough +to make it worth the trouble. + +Some of what's described in this section may change in future releases of GMP. + +@table @asis +@need 1000 +@item HPPA 2.0 + +CPU target @samp{hppa2.0} uses the hppa2.0n 32-bit ABI, but either a 32-bit or +64-bit limb. + +A 64-bit limb is available on HP-UX 10 or up when using @command{c89}. No +@command{gcc} support is planned for 64-bit operations in this ABI. +Applications must be compiled with the same options as GMP, which means + @example -*** config/rs6000/rs6000.md Sun Feb 11 08:22:11 1996 ---- config/rs6000/rs6000.md.new Sun Feb 18 03:33:37 1996 -*************** -*** 920,926 **** - (set (match_operand:SI 0 "gpc_reg_operand" "=r") - (not:SI (match_dup 1)))] - "" -! "nor. %0,%2,%1" - [(set_attr "type" "compare")]) - - (define_insn "" ---- 920,926 ---- - (set (match_operand:SI 0 "gpc_reg_operand" "=r") - (not:SI (match_dup 1)))] - "" -! "nor. %0,%1,%1" - [(set_attr "type" "compare")]) - - (define_insn "" +c89 +DA2.0 +e -D_LONG_LONG_LIMB @end example -@node MP Basics, Reporting Bugs, Installing MP, Top -@comment node-name, next, previous, up -@chapter MP Basics +A 32-bit limb is used in other cases, and no special compiler options are +needed. +CPU target @samp{hppa2.0w} uses the hppa2.0w 64-bit ABI, which is available on +HP-UX 11 or up when using @command{c89}. @command{gcc} support for this is in +progress. Applications must be compiled for the same ABI, which means +@example +c89 +DD64 +@end example + +@need 1000 +@item MIPS 3 and 4 under IRIX 6 + +Targets @samp{mips*-*-irix6*} use the n32 ABI and a 64-bit limb. Applications +must be compiled for the same ABI, which means either + +@example +gcc -mabi=n32 +cc -n32 +@end example + +@need 1000 +@item PowerPC 64 + +CPU target @samp{powerpc64} uses either the 32-bit ABI or the AIX 64-bit ABI. +The latter is used on targets @samp{powerpc64-*-aix*} and applications must be +compiled using either + +@example +gcc -maix64 +xlc -q64 +@end example + +On other systems the 32-bit ABI is used, but with 64-bit limbs provided by +@code{long long} in @command{gcc}. Applications must be compiled using + +@example +gcc -D_LONG_LONG_LIMB +@end example + +@need 1000 +@item Sparc V9 + +On a sparc v9 CPU, either the v8plus 32-bit ABI or v9 64-bit ABI is used. +Targets @samp{ultrasparc*-*-solaris2.[7-9]}, @samp{sparcv9-*-solaris2.[7-9]} +and @samp{sparc64-*-linux*} use the v9 ABI, if the compiler supports it. +Other targets use the v8plus ABI (but with as much of the v9 ISA as possible +in the circumstances). Note that Solaris prior to 2.7 doesn't save all +registers properly, and hence uses the v8plus ABI. + +For the v8plus ABI, applications can be compiled with either + +@example +gcc -mv8plus +cc -xarch=v8plus +@end example + +For the v9 ABI, applications must be compiled with either + +@example +gcc -m64 -mptr64 -Wa,-xarch=v9 -mcpu=v9 +cc -xarch=v9 +@end example + +Don't be confused by the names of these options, they're called @samp{arch} +but they effectively control the ABI. +@end table + + +@need 2000 +@node Notes for Package Builds, Notes for Particular Systems, ABI and ISA, Installing GMP +@section Notes for Package Builds +@cindex Build notes for binary packaging +@cindex Packaged builds + +GMP should present no great difficulties for packaging in a binary +distribution. + +@cindex Libtool versioning +Libtool is used to build the library and @samp{-version-info} is set +appropriately, having started from @samp{3:0:0} in GMP 3.0. The GMP 3 series +will be upwardly binary compatible in each release, but may be adding +additional function interfaces. On systems where libtool versioning is not +fully checked by the loader, an auxiliary mechanism may be needed to express +that a dynamic linked application depends on a new enough minor version of +GMP. + +When building a package for a CPU family, care should be taken to use +@samp{--target} to choose the least common denominator among the CPUs which +might use the package. For example this might necessitate @samp{i386} for +x86s, or plain @samp{sparc} (meaning V7) for SPARCs. + +Users who care about speed will want GMP built for their exact CPU type, to +make use of the available optimizations. Providing a way to suitably rebuild +a package may be useful. This could be as simple as making it possible for a +user to omit @samp{--target} in a build so @samp{./config.guess} will detect +the CPU. But a way to manually specify a @samp{--target} will be wanted for +systems where @samp{./config.guess} is inexact. + + +@need 2000 +@node Notes for Particular Systems, Known Build Problems, Notes for Package Builds, Installing GMP +@section Notes for Particular Systems +@cindex Build notes for particular systems +@table @asis + +@c This section is more or less meant for notes about performance or about +@c build problems that have been worked around but might leave a user +@c scratching their head. Fun with different ABIs on a system belongs in the +@c above section. + +@item AIX 4.3 + +Targets @samp{*-*-aix4.[3-9]*} have shared libraries disabled since they seem +to fail on AIX 4.3. + +@item OpenBSD 2.6 + +@command{m4} in this release of OpenBSD has a bug in @code{eval} that makes it +unsuitable for @file{.asm} file processing. @samp{./configure} will detect +the problem and either abort or choose another m4 in the @env{PATH}. The bug +is fixed in OpenBSD 2.7, so either upgrade or use GNU m4. + +@item Sparc V8 + +Using CPU target @samp{sparcv8} or @samp{supersparc} on relevant systems will +give a significant performance increase over the V7 code. + +@item SunOS 4 + +@command{/usr/bin/m4} lacks various features needed to process @file{.asm} +files, and instead @samp{./configure} will automatically use +@command{/usr/5bin/m4}, which we believe is always available (if not then use +GNU m4). + +@item x86 Pentium and PentiumPro + +The Intel Pentium P5 code is good for its intended P5, but quite slow when run +on Intel P6 class chips (PPro, P-II, P-III)@. @samp{i386} is a better choice +if you're making binaries that must run on both. + +@item x86 MMX and old GAS + +Old versions of GAS don't support MMX instructions, in particular version +1.92.3 that comes with FreeBSD 2.2.8 doesn't (and unfortunately there's no +newer assembler for that system). + +If the target CPU has MMX code but the assembler doesn't support it, a warning +is given and non-MMX code is used instead. This will be an inferior build, +since the MMX code that's present is there because it's faster than the +corresponding plain integer code. + +@item x86 GCC 2.95.2 @samp{-march=pentiumpro} + +GCC 2.95.2 miscompiles @file{mpz/powm.c} when @samp{-march=pentiumpro} is +used, so that option is omitted from the @env{CFLAGS} chosen for relevant +CPUs. The problem is believed to be fixed in GCC 2.96. +@end table + + +@need 2000 +@node Known Build Problems, , Notes for Particular Systems, Installing GMP +@section Known Build Problems +@cindex Build problems known + +@c This section is more or less meant for known build problems that are not +@c otherwise worked around and require some sort of manual intervention. + +You might find more up-to-date information at @uref{http://www.swox.com/gmp/}. + +@table @asis + +@item Generic C on a 64-bit system + +When making a generic C build using @samp{--target=none} on a 64-bit system +(meaning where @code{unsigned long} is 64 bits), @code{BITS_PER_MP_LIMB}, +@code{BITS_PER_LONGINT} and @code{BYTES_PER_MP_LIMB} in +@file{mpn/generic/gmp-mparam.h} need to be changed to 64 and 8. This will +hopefully be automated in a future version of GMP. + +@item NeXT prior to 3.3 + +The system compiler on old versions of NeXT was a massacred and old GCC, even +if it called itself @file{cc}. This compiler cannot be used to build GMP, you +need to get a real GCC, and install that before you compile GMP. (NeXT may +have fixed this in release 3.3 of their system.) + +@item POWER and PowerPC + +Bugs in GCC 2.7.2 (and 2.6.3) mean it can't be used to compile GMP on POWER or +PowerPC. If you want to use GCC for these machines, get GCC 2.7.2.1 (or +later). + +@item Sequent Symmetry + +Use the GNU assembler instead of the system assembler, since the latter has +serious bugs. + +@item Stripped Libraries +@cindex Stripped libraries + +GNU binutils @samp{strip} should not be used on the static libraries +@file{libgmp.a} and @file{libmp.a}, neither directly nor via @samp{make +install-strip}. It can be used on the shared libraries @file{libgmp.so} and +@file{libmp.so} though. + +Currently (binutils 2.10.0), @samp{strip} extracts archives into a single +directory, but GMP contains multiple object files of the same name (eg. three +versions of @file{init.o}), and they overwrite each other, leaving only the +one that happens to be last. + +If stripped static libraries are wanted, the suggested workaround is to build +normally, strip the separate object files, and do another @samp{make all} to +rebuild. Alternately @samp{CFLAGS} with @samp{-g} omitted can always be used +if it's just debugging which is unwanted. + +@item SunOS 4 Native Tools + +The setting for @code{GSYM_PREFIX} in @file{config.m4} may be incorrectly +determined when using the native @command{grep}, leading at link-time to +undefined symbols like @code{___gmpn_add_n}. To fix this, after running +@samp{./configure}, change the relevant line in @file{config.m4} to +@samp{define(, <_>)}. + +The @command{ranlib} command will need to be run manually when building a +static library with the native @command{ar}. After @samp{make}, run +@samp{ranlib .libs/libgmp.a}, and when using @option{--enable-mpbsd} run +@samp{ranlib .libs/libmp.a} too. + +@item VAX running Ultrix + +You need to build and install the GNU assembler before you compile GMP. The VAX +assembly in GMP uses an instruction (@code{jsobgtr}) that cannot be assembled by +the Ultrix assembler. +@end table + + + +@node GMP Basics, Reporting Bugs, Installing GMP, Top +@comment node-name, next, previous, up +@chapter GMP Basics +@cindex Basics + @cindex @file{gmp.h} -All declarations needed to use MP are collected in the include file +All declarations needed to use GMP are collected in the include file @file{gmp.h}. It is designed to work with both C and C++ compilers. +@strong{Using functions, macros, data types, etc.@: not documented in this +manual is strongly discouraged. If you do so your application is guaranteed +to be incompatible with future versions of GMP.} +@menu +* Nomenclature and Types:: Which data types are there? +* Function Classes:: How the functions are organized. +* GMP Variable Conventions:: Some rules and hints about variables. +* GMP and Reentrancy:: What about reentrancy? +* Useful Macros and Constants:: Convenient helpers. +* Compatibility with older versions:: Compatibility issues. +* Getting the Latest Version of GMP:: How to get the software. +@end menu + +@node Nomenclature and Types, Function Classes, GMP Basics, GMP Basics @section Nomenclature and Types +@cindex Nomenclature +@cindex Types @cindex Integer @tindex @code{mpz_t} @noindent In this manual, @dfn{integer} usually means a multiple precision integer, as -defined by the MP library. The C data type for such integers is @code{mpz_t}. +defined by the GMP library. The C data type for such integers is @code{mpz_t}. Here are some examples of how to declare such integers: @example @@ -392,7 +815,7 @@ mpq_t quotient; @tindex @code{mpf_t} @noindent @dfn{Floating point number} or @dfn{Float} for short, is an arbitrary precision -mantissa with an limited precision exponent. The C data type for such objects +mantissa with a limited precision exponent. The C data type for such objects is @code{mpf_t}. @cindex Limb @@ -404,9 +827,11 @@ digit, only larger, and containing several digits.) N 32 or 64 bits. The C data type for a limb is @code{mp_limb_t}. +@node Function Classes, GMP Variable Conventions, Nomenclature and Types, GMP Basics @section Function Classes +@cindex Function classes -There are six classes of functions in the MP library: +There are six classes of functions in the GMP library: @enumerate @item @@ -426,7 +851,7 @@ Functions for floating-point arithmetic, with names be functions is this class. @item -Functions compatible with Berkeley MP, such as @code{itom}, @code{madd}, and +Functions compatible with Berkeley GMP, such as @code{itom}, @code{madd}, and @code{mult}. The associated type is @code{MINT}. @item @@ -438,23 +863,31 @@ from very time-critical user programs. These function The associated type is array of @code{mp_limb_t}. @item -Miscellaneous functions. Functions for setting up custom allocation. +Miscellaneous functions. Functions for setting up custom allocation and +functions for generating random numbers. @end enumerate -@section MP Variable Conventions +@node GMP Variable Conventions, GMP and Reentrancy, Function Classes, GMP Basics +@section GMP Variable Conventions +@cindex Variable conventions +@cindex Parameter conventions +@cindex Conventions for variables -As a general rule, all MP functions expect output arguments before input +As a general rule, all GMP functions expect output arguments before input arguments. This notation is based on an analogy with the assignment operator. (The BSD MP compatibility functions disobey this rule, having the output argument(s) last.) -MP allows you to use the same variable for both input and output in the same -expression. For example, the main function for integer multiplication, -@code{mpz_mul}, can be used like this: @code{mpz_mul (x, x, x)}. This -computes the square of @var{x} and puts the result back in @var{x}. +GMP lets you use the same variable for both input and output in one call. For +example, the main function for integer multiplication, @code{mpz_mul}, can be +used to square @code{x} and put the result back in @code{x} with -Before you can assign to an MP variable, you need to initialize it by calling +@example +mpz_mul (x, x, x); +@end example + +Before you can assign to a GMP variable, you need to initialize it by calling one of the special initialization functions. When you're done with a variable, you need to clear it out, using one of the functions for that purpose. Which function to use depends on the type of variable. See the @@ -465,104 +898,261 @@ A variable should only be initialized once, or at leas each initialization. After a variable has been initialized, it may be assigned to any number of times. -For efficiency reasons, avoid to initialize and clear out a variable in loops. -Instead, initialize it before entering the loop, and clear it out after the -loop has exited. +For efficiency reasons, avoid initializing and clearing out a GMP variable in +a loop. Instead, initialize it before entering the loop, and clear it out +after the loop has exited. -You don't need to be concerned about allocating additional space for MP -variables. All functions in MP automatically allocate additional space when a -variable does not already have enough space. They do not, however, reduce the -space when a smaller number is stored in the object. Most of the time, this -policy is best, since it avoids frequent re-allocation. +GMP variables are small, containing only a couple of sizes, and pointers to +allocated data. Once you have initialized a GMP variable, you don't need to +worry about space allocation. All functions in GMP automatically allocate +additional space when a variable does not already have enough. They do not, +however, reduce the space when a smaller value is stored. Most of the time +this policy is best, since it avoids frequent re-allocation. +When a variable of type @code{mpz_t} is used as a function parameter, it's +effectively a call-by-reference, meaning anything the function does to it will +be be done to the original in the caller. When a function is going to return +an @code{mpz_t} result, it should provide a separate parameter or parameters +that it sets, like the GMP library functions do. A @code{return} of an +@code{mpz_t} doesn't return the object, only a pointer to it, and this is +almost certainly not what you want. All this applies to @code{mpq_t} and +@code{mpf_t} too. +Here's an example function accepting an @code{mpz_t} parameter, doing a +certain calculation, and returning a result. + +@example +void +myfunction (mpz_t result, mpz_t param, unsigned long n) +@{ + unsigned long i; + + mpz_mul_ui (result, param, n); + for (i = 1; i < n; i++) + mpz_add_ui (result, result, i*7); +@} + +int +main (void) +@{ + mpz_t r, n; + mpz_init (r); + mpz_init_set_str (n, "123456", 0); + + myfunction (r, n, 20L); + mpz_out_str (stdout, 10, r); printf ("\n"); + + return 0; +@} +@end example + +This example will work if @code{result} and @code{param} are the same +variable, just like the library functions. But sometimes this is tricky to +arrange, and an application might not want to bother for its own subroutines. + +@code{mpz_t} is actually implemented as a one-element array of a certain +structure type. This is why using it to declare a variable gives an object +with the fields GMP needs, but then using it as a parameter passes a pointer +to the object. Note that the actual contents of an @code{mpz_t} are for +internal use only and you should not access them directly if you want your +code to be compatible with future GMP releases. + + +@node GMP and Reentrancy, Useful Macros and Constants, GMP Variable Conventions, GMP Basics +@section GMP and Reentrancy +@cindex Reentrancy +@cindex Thread safety +@cindex Multi-threading + +The GMP code is reentrant and thread-safe, with some exceptions: + +@itemize @bullet +@item +The function @code{mpf_set_default_prec} saves the selected precision in +a global variable. + +@item +The function @code{mp_set_memory_functions} uses several global +variables for storing the selected memory allocation functions. + +@item +If the memory allocation functions set by a call to +@code{mp_set_memory_functions} (or @code{malloc} and friends by default) are +not reentrant, GMP will not be reentrant either. + +@item +The old random number functions (@code{mpz_random}, etc) use a random number +generator from the C library, usually @code{mrand48} or @code{random}. These +routines are not reentrant, since they rely on global state. +(However the newer random number functions that accept a +@code{gmp_randstate_t} parameter are reentrant.) +@end itemize + + +@need 2000 +@node Useful Macros and Constants, Compatibility with older versions, GMP and Reentrancy, GMP Basics @section Useful Macros and Constants +@cindex Useful macros and constants +@cindex Constants @deftypevr {Global Constant} {const int} mp_bits_per_limb +@cindex Bits per limb +@cindex Limb size The number of bits per limb. @end deftypevr @defmac __GNU_MP_VERSION @defmacx __GNU_MP_VERSION_MINOR -The major and minor MP version, respectively, as integers. +@defmacx __GNU_MP_VERSION_PATCHLEVEL +@cindex Version number +@cindex GMP version number +The major and minor GMP version, and patch level, respectively, as integers. +For GMP i.j, these numbers will be i, j, and 0, respectively. +For GMP i.j.k, these numbers will be i, j, and k, respectively. @end defmac -@section Compatibility with Version 1.x -This version of MP is upward compatible with previous versions of MP, with a -few exceptions. +@node Compatibility with older versions, Getting the Latest Version of GMP, Useful Macros and Constants, GMP Basics +@section Compatibility with older versions +@cindex Compatibility with older versions +@cindex Upward compatibility -@enumerate -@item Integer division functions round the result differently. The old -functions (@code{mpz_div}, @code{mpz_divmod}, @code{mpz_mdiv}, -@code{mpz_mdivmod}, etc) now all use floor rounding (i.e., they round the -quotient to @minus{}infinity). There are a lot of new functions for integer -division, giving the user better control over the rounding. +This version of GMP is upwardly binary compatible with versions 3.0 and 3.0.1, +and upwardly compatible at the source level with versions 2.0, 2.0.1, and +2.0.2, with the following exceptions. -@item The function @code{mpz_mod} now compute the true @strong{mod} function. +@itemize @bullet +@item +@code{mpn_gcd} had its source arguments swapped as of GMP 3.0 for consistency +with other @code{mpn} functions. -@item The functions @code{mpz_powm} and @code{mpz_powm_ui} now use -@strong{mod} for reduction. +@item +@code{mpf_get_prec} counted precision slightly differently in GMP 3.0 and +3.0.1, but in 3.1 has reverted to the 2.0.x style. -@item The assignment functions for rational numbers do no longer canonicalize -their results. In the case a non-canonical result could arise from an -assignment, the user need to insert an explicit call to -@code{mpq_canonicalize}. This change was made for efficiency. +@end itemize -@item Output generated by @code{mpz_out_raw} in this release cannot be read -by @code{mpz_inp_raw} in previous releases. This change was made for making -the file format truly portable between machines with different word sizes. +There are a number of compatibility issues between GMP 1 and GMP 2 that of +course also apply when porting applications from GMP 1 to GMP 3. Please +see the GMP 2 manual for details. -@item Several @code{mpn} functions have changed. But they were intentionally -undocumented in previous releases. +@c @enumerate +@c @item Integer division functions round the result differently. The obsolete +@c functions (@code{mpz_div}, @code{mpz_divmod}, @code{mpz_mdiv}, +@c @code{mpz_mdivmod}, etc) now all use floor rounding (i.e., they round the +@c quotient towards +@c @ifinfo +@c @minus{}infinity). +@c @end ifinfo +@c @iftex +@c @tex +@c $-\infty$). +@c @end tex +@c @end iftex +@c There are a lot of functions for integer division, giving the user better +@c control over the rounding. -@item The functions @code{mpz_cmp_ui}, @code{mpz_cmp_si}, and @code{mpq_cmp_ui} -are now implementated as macros, and thereby sometimes evaluate their -arguments multiple times. +@c @item The function @code{mpz_mod} now compute the true @strong{mod} function. -@item The functions @code{mpz_pow_ui} and @code{mpz_ui_pow_ui} now yield 1 -for 0^0. (In version 1, they yielded 0.) +@c @item The functions @code{mpz_powm} and @code{mpz_powm_ui} now use +@c @strong{mod} for reduction. -@end enumerate +@c @item The assignment functions for rational numbers do no longer canonicalize +@c their results. In the case a non-canonical result could arise from an +@c assignment, the user need to insert an explicit call to +@c @code{mpq_canonicalize}. This change was made for efficiency. +@c @item Output generated by @code{mpz_out_raw} in this release cannot be read +@c by @code{mpz_inp_raw} in previous releases. This change was made for making +@c the file format truly portable between machines with different word sizes. -@section Getting the Latest Version of MP +@c @item Several @code{mpn} functions have changed. But they were intentionally +@c undocumented in previous releases. -The latest version of the MP library is available by anonymous ftp from -from @samp{prep.ai.mit.edu}. The file name is -@file{/pub/gnu/gmp-M.N.tar.gz}. Many sites around the world mirror -@samp{prep}; please use a mirror site near you. +@c @item The functions @code{mpz_cmp_ui}, @code{mpz_cmp_si}, and @code{mpq_cmp_ui} +@c are now implemented as macros, and thereby sometimes evaluate their +@c arguments multiple times. -@node Reporting Bugs, Integer Functions, MP Basics, Top +@c @item The functions @code{mpz_pow_ui} and @code{mpz_ui_pow_ui} now yield 1 +@c for 0^0. (In version 1, they yielded 0.) + +@c @end enumerate + + +@node Getting the Latest Version of GMP, , Compatibility with older versions, GMP Basics +@section Getting the Latest Version of GMP +@cindex Latest version of GMP +@cindex Anonymous FTP of latest version +@cindex FTP of latest version + +The latest version of the GMP library is available at +@uref{ftp://ftp.gnu.org/pub/gnu/gmp}. Many sites around the world mirror +@samp{ftp.gnu.org}; please use a mirror site near you, see +@uref{http://www.gnu.org/order/ftp.html}. + + +@node Reporting Bugs, Integer Functions, GMP Basics, Top @comment node-name, next, previous, up @chapter Reporting Bugs @cindex Reporting bugs +@cindex Bug reporting -If you think you have found a bug in the MP library, please investigate it and -report it. We have made this library available to you, and it is not to ask -too much from you, to ask you to report the bugs that you find. +If you think you have found a bug in the GMP library, please investigate it +and report it. We have made this library available to you, and it is not too +much to ask you to report the bugs you find. Before you report a bug, you may +want to check @uref{http://www.swox.com/gmp/} for patches for this release. -There are a few things you should think about when you put your bug report -together. +Please include the following in any report, -You have to send us a test case that makes it possible for us to reproduce the -bug. Include instructions on how to run the test case. +@itemize @bullet +@item +The GMP version number, and if pre-packaged or patched then say so. -You also have to explain what is wrong; if you get a crash, or if the results -printed are incorrect and in that case, in what way. +@item +A test program that makes it possible for us to reproduce the bug. Include +instructions on how to run the program. +@item +A description of what is wrong. If the results are incorrect, in what way. +If you get a crash, say so. + +@item +If you get a crash, include a stack backtrace from the debugger if it's +informative (@samp{where} in @command{gdb}, or @samp{$C} in @command{adb}). + +@item +@strong{Please do not send core dumps, executables or @command{strace}s.} + +@item +The configuration options you used when building GMP, if any. + +@item +The name of the compiler and its version. For @command{gcc}, get the version +with @samp{gcc -v}, otherwise perhaps @samp{what `which cc`}, or similar. + +@item +The output from running @samp{uname -a}. + +@item +The output from running @samp{./config.guess}. + +@item +If the bug is related to @samp{configure}, then the contents of +@file{config.log}. + +@item +If the bug is related to an @file{asm} file not assembling, then the contents +of @file{config.m4}. +@end itemize + It is not uncommon that an observed problem is actually due to a bug in the -compiler used when building MP; the MP code tends to explore interesting -corners in compilers. Therefore, please include compiler version information -in your bug report. This can be extracted using @samp{what `which cc`}, or, -if you're using gcc, @samp{gcc -v}. Also, include the output from @samp{uname --a}. +compiler; the GMP code tends to explore interesting corners in compilers. -If your bug report is good, we will do our best to help you to get a corrected +If your bug report is good, we will do our best to help you get a corrected version of the library; if the bug report is poor, we won't do anything about -it (aside of chiding you to send better bug reports). +it (except maybe ask you to send a better report). -Send your bug report to: @samp{bug-gmp@@prep.ai.mit.edu}. +Send your report to: @email{bug-gmp@@gnu.org}. If you think something in this manual is unclear, or downright incorrect, or if the language needs to be improved, please send a note to the same address. @@ -573,26 +1163,33 @@ the language needs to be improved, please send a note @chapter Integer Functions @cindex Integer functions -This chapter describes the MP functions for performing integer arithmetic. +This chapter describes the GMP functions for performing integer arithmetic. These functions start with the prefix @code{mpz_}. -Arbitrary precision integers are stored in objects of type @code{mpz_t}. +GMP integers are stored in objects of type @code{mpz_t}. @menu -* Initializing Integers:: -* Assigning Integers:: -* Simultaneous Integer Init & Assign:: -* Converting Integers:: -* Integer Arithmetic:: -* Comparison Functions:: -* Integer Logic and Bit Fiddling:: -* I/O of Integers:: -* Miscellaneous Integer Functions:: +* Initializing Integers:: +* Assigning Integers:: +* Simultaneous Integer Init & Assign:: +* Converting Integers:: +* Integer Arithmetic:: +* Integer Division:: +* Integer Exponentiation:: +* Integer Roots:: +* Number Theoretic Functions:: +* Integer Comparisons:: +* Integer Logic and Bit Fiddling:: +* I/O of Integers:: +* Integer Random Numbers:: +* Miscellaneous Integer Functions:: @end menu -@node Initializing Integers, Assigning Integers, , Integer Functions +@node Initializing Integers, Assigning Integers, Integer Functions, Integer Functions @comment node-name, next, previous, up -@section Initialization and Assignment Functions +@section Initialization Functions +@cindex Integer initialization functions +@cindex Initialization functions The functions for integer arithmetic assume that all integer objects are initialized. You do that by calling the function @code{mpz_init}. @@ -652,8 +1249,9 @@ Don't call @code{mpz_clear}! @node Assigning Integers, Simultaneous Integer Init & Assign, Initializing Integers, Integer Functions @comment node-name, next, previous, up -@subsection Assignment Functions +@section Assignment Functions @cindex Integer assignment functions +@cindex Assignment functions These functions assign new values to already initialized integers (@pxref{Initializing Integers}). @@ -677,15 +1275,28 @@ assumed, otherwise decimal is assumed. This function returns 0 if the entire string up to the '\0' is a valid number in base @var{base}. Otherwise it returns @minus{}1. + +[It turns out that it is not entirely true that this function ignores +white-space. It does ignore it between digits, but not after a minus sign +or within or after "0x". We are considering changing the definition of +this function, making it fail when there is any white-space in the input, +since that makes a lot of sense. Please tell us your opinion about this +change. Do you really want it to accept "3 14" as meaning 314 as it does +now?] @end deftypefun +@deftypefun void mpz_swap (mpz_t @var{rop1}, mpz_t @var{rop2}) +Swap the values @var{rop1} and @var{rop2} efficiently. +@end deftypefun + @node Simultaneous Integer Init & Assign, Converting Integers, Assigning Integers, Integer Functions @comment node-name, next, previous, up -@subsection Combined Initialization and Assignment Functions +@section Combined Initialization and Assignment Functions @cindex Initialization and assignment functions +@cindex Integer init and assign -For convenience, MP provides a parallel series of initialize-and-set functions +For convenience, GMP provides a parallel series of initialize-and-set functions which initialize the output and then store the value there. These functions' names have the form @code{mpz_init_set@dots{}} @@ -726,21 +1337,28 @@ an error occurs. (I.e., you have to call @code{mpz_cl @end deftypefun -@node Converting Integers, Integer Arithmetic, Simultaneous Integer Init & Assign, Integer Functions +@node Converting Integers, Integer Arithmetic, Simultaneous Integer Init & Assign, Integer Functions @comment node-name, next, previous, up @section Conversion Functions @cindex Integer conversion functions @cindex Conversion functions -This section describes functions for converting arbitrary precision integers -to standard C types. Functions for converting @emph{to} arbitrary -precision integers are described in @ref{Assigning Integers} and @ref{I/O of -Integers}. +This section describes functions for converting GMP integers to standard C +types. Functions for converting @emph{to} GMP integers are described in +@ref{Assigning Integers} and @ref{I/O of Integers}. +@deftypefun mp_limb_t mpz_getlimbn (mpz_t @var{op}, mp_size_t @var{n}) +Return limb #@var{n} from @var{op}. This function allows for very efficient +decomposition of a number in its limbs. + +The function @code{mpz_size} can be used to determine the useful range for +@var{n}. +@end deftypefun + @deftypefun {unsigned long int} mpz_get_ui (mpz_t @var{op}) -Return the least significant part from @var{op}. This function combined -with @* @code{mpz_tdiv_q_2exp(@dots{}, @var{op}, CHAR_BIT*sizeof(unsigned -long int))} can be used to extract the limbs of an integer. +Return the least significant part from @var{op}. This function combined with +@* @code{mpz_tdiv_q_2exp(@dots{}, @var{op}, CHAR_BIT*sizeof(unsigned long +int))} can be used to decompose an integer into unsigned longs. @end deftypefun @deftypefun {signed long int} mpz_get_si (mpz_t @var{op}) @@ -749,8 +1367,8 @@ Otherwise return the least significant part of @var{op as @var{op}. If @var{op} is too large to fit in a @code{signed long int}, the returned -result is probably not very useful. @c To find out if the value will fit, use -@c the function @code{mpz_fits_si}. +result is probably not very useful. To find out if the value will fit, use +the function @code{mpz_fits_slong_p}. @end deftypefun @deftypefun double mpz_get_d (mpz_t @var{op}) @@ -761,18 +1379,22 @@ Convert @var{op} to a double. Convert @var{op} to a string of digits in base @var{base}. The base may vary from 2 to 36. -If @var{str} is NULL, space for the result string is allocated using the -default allocation function, and a pointer to the string is returned. +If @var{str} is @code{NULL}, space for the result string is allocated using the +default allocation function. -If @var{str} is not NULL, it should point to a block of storage enough large +If @var{str} is not @code{NULL}, it should point to a block of storage enough large for the result. To find out the right amount of space to provide for @var{str}, use @code{mpz_sizeinbase (@var{op}, @var{base}) + 2}. The two extra bytes are for a possible minus sign, and for the terminating null character. + +A pointer to the result string is returned. This pointer will will either +equal @var{str}, or if that is @code{NULL}, will point to the allocated storage. @end deftypefun -@node Integer Arithmetic, Comparison Functions, Converting Integers, Integer Functions +@need 2000 +@node Integer Arithmetic, Integer Division, Converting Integers, Integer Functions @comment node-name, next, previous, up @section Arithmetic Functions @cindex Integer arithmetic functions @@ -780,14 +1402,12 @@ character. @deftypefun void mpz_add (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) @deftypefunx void mpz_add_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -@ifinfo +@ifnottex Set @var{rop} to @var{op1} + @var{op2}. -@end ifinfo -@iftex +@end ifnottex @tex Set @var{rop} to $@var{op1} + @var{op2}$. @end tex -@end iftex @end deftypefun @deftypefun void mpz_sub (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) @@ -796,28 +1416,35 @@ Set @var{rop} to @var{op1} @minus{} @var{op2}. @end deftypefun @deftypefun void mpz_mul (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) +@deftypefunx void mpz_mul_si (mpz_t @var{rop}, mpz_t @var{op1}, long int @var{op2}) @deftypefunx void mpz_mul_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -@ifinfo +@ifnottex Set @var{rop} to @var{op1} times @var{op2}. -@end ifinfo -@iftex +@end ifnottex @tex Set @var{rop} to $@var{op1} \times @var{op2}$. @end tex -@end iftex @end deftypefun +@deftypefun void mpz_addmul_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) +@ifnottex +Add @var{op1} times @var{op2} to @var{rop}. +@end ifnottex +@tex +Set @var{rop} to $@var{rop} + @var{op1} \times @var{op2}$. +@end tex +@end deftypefun + @deftypefun void mpz_mul_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -@ifinfo +@cindex Bit shift left +@ifnottex Set @var{rop} to @var{op1} times 2 raised to @var{op2}. This operation can also be defined as a left shift, @var{op2} steps. -@end ifinfo -@iftex +@end ifnottex @tex Set @var{rop} to $@var{op1} \times 2^{op2}$. This operation can also be defined as a left shift, @var{op2} steps. @end tex -@end iftex @end deftypefun @deftypefun void mpz_neg (mpz_t @var{rop}, mpz_t @var{op}) @@ -828,33 +1455,45 @@ Set @var{rop} to @minus{}@var{op}. Set @var{rop} to the absolute value of @var{op}. @end deftypefun -@deftypefun void mpz_fac_ui (mpz_t @var{rop}, unsigned long int @var{op}) -Set @var{rop} to @var{op}!, the factorial of @var{op}. -@end deftypefun -@subsection Division functions +@need 2000 +@node Integer Division, Integer Exponentiation, Integer Arithmetic, Integer Functions +@section Division Functions +@cindex Integer division functions +@cindex Division functions -Division is undefined if the divisor is zero, and passing a zero divisor to -the divide or modulo functions, as well passing a zero mod argument to the +Division is undefined if the divisor is zero, and passing a zero divisor to the +divide or modulo functions, as well passing a zero mod argument to the @code{mpz_powm} and @code{mpz_powm_ui} functions, will make these functions -intentionally divide by zero. This gives the user the possibility to handle -arithmetic exceptions in these functions in the same manner as other -arithmetic exceptions. +intentionally divide by zero. This lets the user handle arithmetic exceptions +in these functions in the same manner as other arithmetic exceptions. There are three main groups of division functions: @itemize @bullet @item -Functions that truncate the quotient towards 0. The names of these -functions start with @code{mpz_tdiv}. The @samp{t} in the name is short for +Functions that truncate the quotient towards 0. The names of these functions +start with @code{mpz_tdiv}. The @samp{t} in the name is short for @samp{truncate}. @item -Functions that round the quotient towards @minus{}infinity. The names of -these routines start with @code{mpz_fdiv}. The @samp{f} in the name is -short for @samp{floor}. +Functions that round the quotient towards +@ifnottex +@minus{}infinity). +@end ifnottex +@tex +$-\infty$ +@end tex +The names of these routines start with @code{mpz_fdiv}. The @samp{f} in the +name is short for @samp{floor}. @item -Functions that round the quotient towards +infinity. The names of -these routines start with @code{mpz_cdiv}. The @samp{c} in the name is -short for @samp{ceil}. +Functions that round the quotient towards +@ifnottex ++infinity. +@end ifnottex +@tex +$+\infty$ +@end tex +The names of these routines start with @code{mpz_cdiv}. The @samp{c} in the +name is short for @samp{ceil}. @end itemize For each rounding mode, there are a couple of variants. Here @samp{q} means @@ -862,271 +1501,360 @@ that the quotient is computed, while @samp{r} means th computed. Functions that compute both the quotient and remainder have @samp{qr} in the name. -@deftypefun void mpz_tdiv_q (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) -@deftypefunx void mpz_tdiv_q_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -Set @var{rop} to [@var{op1}/@var{op2}]. The quotient is truncated towards -0. -@end deftypefun +@deftypefun void mpz_tdiv_q (mpz_t @var{q}, mpz_t @var{n}, mpz_t @var{d}) +@deftypefunx {unsigned long int} mpz_tdiv_q_ui (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d}) +Set @var{q} to [@var{n}/@var{d}], truncated towards 0. -@deftypefun void mpz_tdiv_r (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) -@deftypefunx void mpz_tdiv_r_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -Set @var{rop} to (@var{op1} - [@var{op1}/@var{op2}] * @var{op2}). -Unless the remainder is zero, it has the same sign as the dividend. +The function @code{mpz_tdiv_q_ui} returns the absolute value of the true +remainder. @end deftypefun -@deftypefun void mpz_tdiv_qr (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, mpz_t @var{op2}) -@deftypefunx void mpz_tdiv_qr_ui (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, unsigned long int @var{op2}) -Divide @var{op1} by @var{op2} and put the quotient in @var{rop1} and the -remainder in @var{rop2}. The quotient is rounded towards 0. Unless the -remainder is zero, it has the same sign as the dividend. +@deftypefun void mpz_tdiv_r (mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d}) +@deftypefunx {unsigned long int} mpz_tdiv_r_ui (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) +@ifnottex +Set @var{r} to (@var{n} - [@var{n}/@var{d}] * @var{d}), where the quotient is +truncated towards 0. Unless @var{r} becomes zero, it will get the same sign as +@var{n}. +@end ifnottex +@tex +Set @var{r} to $(@var{n} - [@var{n}/@var{d}] \times @var{d})$, where the +quotient is truncated towards 0. Unless @var{r} becomes zero, it will get the +same sign as @var{n}. +@end tex -If @var{rop1} and @var{rop2} are the same variable, the results are -undefined. +The function @code{mpz_tdiv_r_ui} returns the absolute value of the remainder. @end deftypefun -@deftypefun void mpz_fdiv_q (mpz_t @var{rop1}, mpz_t @var{op1}, mpz_t @var{op2}) -@deftypefunx void mpz_fdiv_q_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -@ifinfo -Set @var{rop} to @var{op1}/@var{op2}. The quotient is rounded towards -@minus{}infinity. -@end ifinfo -@iftex +@deftypefun void mpz_tdiv_qr (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d}) +@deftypefunx {unsigned long int} mpz_tdiv_qr_ui (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) +@ifnottex +Set @var{q} to [@var{n}/@var{d}], truncated towards 0. Set @var{r} to (@var{n} +- [@var{n}/@var{d}] * @var{d}). Unless @var{r} becomes zero, it will get the +same sign as @var{n}. If @var{q} and @var{r} are the same variable, the +results are undefined. +@end ifnottex @tex -Set @var{rop} to $\lfloor@var{op1}/@var{op2}\rfloor$. (I.e., round -the quotient towards $-\infty$.) +Set @var{q} to [@var{n}/@var{d}], truncated towards 0. Set @var{r} to $(@var{n} +- [@var{n}/@var{d}] \times @var{d})$. Unless @var{r} becomes zero, it will get the +same sign as @var{n}. If @var{q} and @var{r} are the same variable, the +results are undefined. @end tex -@end iftex + +The function @code{mpz_tdiv_qr_ui} returns the absolute value of the remainder. @end deftypefun -@deftypefun void mpz_fdiv_r (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) -@deftypefunx {unsigned long int} mpz_fdiv_r_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -Divide @var{op1} by @var{op2} and put the remainder in @var{rop}. Unless -the remainder is zero, it has the same sign as the divisor. +@deftypefun {unsigned long int} mpz_tdiv_ui (mpz_t @var{n}, unsigned long int @var{d}) +Like @code{mpz_tdiv_r_ui}, but the remainder is not stored anywhere; its +absolute value is just returned. +@end deftypefun -For @code{mpz_fdiv_r_ui} the remainder is small enough to fit in an -@code{unsigned long int}, and is therefore returned. +@deftypefun void mpz_fdiv_q (mpz_t @var{q}, mpz_t @var{n}, mpz_t @var{d}) +@deftypefunx {unsigned long int} mpz_fdiv_q_ui (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d}) +@ifnottex +Set @var{q} to @var{n}/@var{d}, rounded towards @minus{}infinity. +@end ifnottex +@tex +Set @var{q} to $\lfloor@var{n}/@var{d}\rfloor$. +@end tex + +The function @code{mpz_fdiv_q_ui} returns the remainder. @end deftypefun -@deftypefun void mpz_fdiv_qr (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, mpz_t @var{op2}) -@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}) -Divide @var{op1} by @var{op2} and put the quotient in @var{rop1} and the -remainder in @var{rop2}. The quotient is rounded towards @minus{}infinity. -Unless the remainder is zero, it has the same sign as the divisor. +@deftypefun void mpz_fdiv_r (mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d}) +@deftypefunx {unsigned long int} mpz_fdiv_r_ui (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) +@ifnottex +Set @var{r} to (@var{n} - @var{n}/@var{d} * @var{d}), where the quotient is +rounded towards @minus{}infinity. Unless @var{r} becomes zero, it will get the +same sign as @var{d}. +@end ifnottex +@tex +Set @var{r} to $(@var{n} - \lfloor@var{n}/@var{d}\rfloor \times @var{d})$. +Unless @var{r} becomes zero, it will get the same sign as @var{d}. +@end tex -For @code{mpz_fdiv_qr_ui} the remainder is small enough to fit in an -@code{unsigned long int}, and is therefore returned. +The function @code{mpz_fdiv_r_ui} returns the remainder. +@end deftypefun -If @var{rop1} and @var{rop2} are the same variable, the results are -undefined. +@deftypefun void mpz_fdiv_qr (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d}) +@deftypefunx {unsigned long int} mpz_fdiv_qr_ui (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) +@ifnottex +Set @var{q} to @var{n}/@var{d}, rounded towards @minus{}infinity. Set @var{r} +to (@var{n} - @var{n}/@var{d} * @var{d}). Unless @var{r} becomes zero, it +will get the same sign as @var{d}. If @var{q} and @var{r} are the same +variable, the results are undefined. +@end ifnottex +@tex +Set @var{q} to $\lfloor@var{n}/@var{d}\rfloor$. Set @var{r} to $(@var{n} - +\lfloor@var{n}/@var{d}\rfloor \times @var{d})$. Unless @var{r} becomes zero, +it will get the same sign as @var{d}. If @var{q} and @var{r} are the same +variable, the results are undefined. +@end tex + +The function @code{mpz_fdiv_qr_ui} returns the remainder. @end deftypefun -@deftypefun {unsigned long int} mpz_fdiv_ui (mpz_t @var{op1}, unsigned long int @var{op2}) -This function is similar to @code{mpz_fdiv_r_ui}, but the remainder is only -returned; it is not stored anywhere. +@deftypefun {unsigned long int} mpz_fdiv_ui (mpz_t @var{n}, unsigned long int @var{d}) +Like @code{mpz_fdiv_r_ui}, but the remainder is not stored anywhere; it is just +returned. @end deftypefun -@deftypefun void mpz_cdiv_q (mpz_t @var{rop1}, mpz_t @var{op1}, mpz_t @var{op2}) -@deftypefunx void mpz_cdiv_q_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -@ifinfo -Set @var{rop} to @var{op1}/@var{op2}. The quotient is rounded towards -+infinity. -@end ifinfo -@iftex +@deftypefun void mpz_cdiv_q (mpz_t @var{q}, mpz_t @var{n}, mpz_t @var{d}) +@deftypefunx {unsigned long int} mpz_cdiv_q_ui (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d}) +@ifnottex +Set @var{q} to @var{n}/@var{d}, rounded towards +infinity. +@end ifnottex @tex -Set @var{rop} to $\lceil@var{op1}/@var{op2}\rceil$. (I.e., round the -quotient towards $+\infty$.) +Set @var{q} to $\lceil@var{n}/@var{d}\rceil$. @end tex -@end iftex + +The function @code{mpz_cdiv_q_ui} returns the negated remainder. @end deftypefun -@deftypefun void mpz_cdiv_r (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) -@deftypefunx {unsigned long int} mpz_cdiv_r_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -Divide @var{op1} by @var{op2} and put the remainder in @var{rop}. Unless -the remainder is zero, it has the opposite sign as the divisor. +@deftypefun void mpz_cdiv_r (mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d}) +@deftypefunx {unsigned long int} mpz_cdiv_r_ui (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) +@ifnottex +Set @var{r} to (@var{n} - @var{n}/@var{d} * @var{d}), where the quotient is +rounded towards +infinity. Unless @var{r} becomes zero, it will get the +opposite sign as @var{d}. +@end ifnottex +@tex +Set @var{r} to $(@var{n} - \lceil@var{n}/@var{d}\rceil \times @var{d})$. Unless +@var{r} becomes zero, it will get the opposite sign as @var{d}. +@end tex -For @code{mpz_cdiv_r_ui} the negated remainder is small enough to fit in an -@code{unsigned long int}, and it is therefore returned. +The function @code{mpz_cdiv_r_ui} returns the negated remainder. @end deftypefun -@deftypefun void mpz_cdiv_qr (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, mpz_t @var{op2}) -@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}) -Divide @var{op1} by @var{op2} and put the quotient in @var{rop1} and the -remainder in @var{rop2}. The quotient is rounded towards +infinity. Unless -the remainder is zero, it has the opposite sign as the divisor. +@deftypefun void mpz_cdiv_qr (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d}) +@deftypefunx {unsigned long int} mpz_cdiv_qr_ui (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) +@ifnottex +Set @var{q} to @var{n}/@var{d}, rounded towards +infinity. Set @var{r} +to (@var{n} - @var{n}/@var{d} * @var{d}). Unless @var{r} becomes zero, it +will get the opposite sign as @var{d}. If @var{q} and @var{r} are the same +variable, the results are undefined. +@end ifnottex +@tex +Set @var{q} to $\lceil@var{n}/@var{d}\rceil$. Set @var{r} to $(@var{n} - +\lceil@var{n}/@var{d}\rceil \times @var{d})$. Unless @var{r} becomes zero, it will +get the opposite sign as @var{d}. If @var{q} and @var{r} are the same +variable, the results are undefined. +@end tex -For @code{mpz_cdiv_qr_ui} the negated remainder is small enough to fit in an -@code{unsigned long int}, and it is therefore returned. - -If @var{rop1} and @var{rop2} are the same variable, the results are -undefined. +The function @code{mpz_cdiv_qr_ui} returns the negated remainder. @end deftypefun -@deftypefun {unsigned long int} mpz_cdiv_ui (mpz_t @var{op1}, unsigned long int @var{op2}) -Return the negated remainder, similar to @code{mpz_cdiv_r_ui}. (The -difference is that this function doesn't store the remainder anywhere.) +@deftypefun {unsigned long int} mpz_cdiv_ui (mpz_t @var{n}, unsigned long int @var{d}) +Like @code{mpz_tdiv_r_ui}, but the remainder is not stored anywhere; its +negated value is just returned. @end deftypefun -@deftypefun void mpz_mod (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) -@deftypefunx {unsigned long int} mpz_mod_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -Set @var{rop} to @var{op1} @code{mod} @var{op2}. The sign of the divisor is -ignored, and the result is always non-negative. +@deftypefun void mpz_mod (mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d}) +@deftypefunx {unsigned long int} mpz_mod_ui (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) +Set @var{r} to @var{n} @code{mod} @var{d}. The sign of the divisor is ignored; +the result is always non-negative. -For @code{mpz_mod_ui} the remainder is small enough to fit in an -@code{unsigned long int}, and is therefore returned. +The function @code{mpz_mod_ui} returns the remainder. @end deftypefun -@deftypefun void mpz_divexact (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) -Set @var{rop} to @var{op1}/@var{op2}. This function produces correct -results only when it is known in advance that @var{op2} divides -@var{op1}. +@deftypefun void mpz_divexact (mpz_t @var{q}, mpz_t @var{n}, mpz_t @var{d}) +@cindex Exact division functions +Set @var{q} to @var{n}/@var{d}. This function produces correct results only +when it is known in advance that @var{d} divides @var{n}. Since mpz_divexact is much faster than any of the other routines that produce -the quotient (@pxref{References} Jebelean), it is the best choice for -instances in which exact division is known to occur, such as reducing a -rational to lowest terms. +the quotient (@pxref{References} Jebelean), it is the best choice for instances +in which exact division is known to occur, such as reducing a rational to +lowest terms. @end deftypefun -@deftypefun void mpz_tdiv_q_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -@ifinfo -Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}. The quotient is -rounded towards 0. -@end ifinfo -@iftex +@deftypefun void mpz_tdiv_q_2exp (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d}) +@cindex Bit shift right +@ifnottex +Set @var{q} to @var{n} divided by 2 raised to @var{d}. The quotient is truncated +towards 0. +@end ifnottex @tex -Set @var{rop} to $@var{op1}/2^{op2}$. The quotient is rounded towards 0. +Set @var{q} to $[{n}/2^{d}]$, truncated towards 0. @end tex -@end iftex @end deftypefun -@deftypefun void mpz_tdiv_r_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -@ifinfo -Divide @var{op1} by (2 raised to @var{op2}) and put the remainder in -@var{rop}. Unless it is zero, @var{rop} will have the same sign as @var{op1}. -@end ifinfo -@iftex +@deftypefun void mpz_tdiv_r_2exp (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) +@ifnottex +Divide @var{n} by (2 raised to @var{d}), rounding the quotient towards 0, and +put the remainder in @var{r}. +@end ifnottex @tex -Divide @var{op1} by $2^{op2}$ and put the remainder in @var{rop}. Unless it is -zero, @var{rop} will have the same sign as @var{op1}. +Set @var{r} to $n - [n / 2^{d}] \times 2^{d}$, where [ ] indicates rounding towards +0. @end tex -@end iftex +Unless it is zero, @var{r} will have the same sign as @var{n}. @end deftypefun -@deftypefun void mpz_fdiv_q_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -@ifinfo -Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}. The quotient is -rounded towards @minus{}infinity. -@end ifinfo -@iftex +@deftypefun void mpz_fdiv_q_2exp (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d}) +@ifnottex +Set @var{q} to @var{n} divided by 2 raised to @var{d}, rounded towards +@minus{}infinity. +@end ifnottex @tex -Set @var{rop} to $\lfloor@var{op1}/2^{op2}\rfloor$. The quotient is rounded -towards $-\infty$. +Set @var{q} to $\lfloor{n}/2^{d}\rfloor$. @end tex -@end iftex +This operation can also be defined as arithmetic right shift @var{d} bit +positions. @end deftypefun -@deftypefun void mpz_fdiv_r_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) -@ifinfo -Divide @var{op1} by (2 raised to @var{op2}) and put the remainder in -@var{rop}. The sign of @var{rop} will always be positive. -@end ifinfo -@iftex +@deftypefun void mpz_fdiv_r_2exp (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) +@ifnottex +Divide @var{n} by (2 raised to @var{d}), rounding the quotient towards +@minus{}infinity, and put the remainder in @var{r}. +@end ifnottex @tex -Divide @var{op1} by $2^{op2}$ and put the remainder in @var{rop}. The sign of -@var{rop} will always be positive. +Set @var{r} to $n - \lfloor{n}/2^{d}\rfloor \times 2^{d}$. @end tex -@end iftex - -This operation can also be defined as masking of the @var{op2} least -significant bits. +The sign of @var{r} will always be positive. +This operation can also be defined as masking of the @var{d} least significant +bits. @end deftypefun -@subsection Exponentialization Functions +@need 2000 +@node Integer Exponentiation, Integer Roots, Integer Division, Integer Functions +@section Exponentiation Functions +@cindex Integer exponentiation functions +@cindex Exponentiation functions + @deftypefun void mpz_powm (mpz_t @var{rop}, mpz_t @var{base}, mpz_t @var{exp}, mpz_t @var{mod}) @deftypefunx void mpz_powm_ui (mpz_t @var{rop}, mpz_t @var{base}, unsigned long int @var{exp}, mpz_t @var{mod}) +@ifnottex Set @var{rop} to (@var{base} raised to @var{exp}) @code{mod} @var{mod}. If @var{exp} is negative, the result is undefined. +@end ifnottex +@tex +Set @var{rop} to $base^{exp} \bmod mod$. If +@var{exp} is negative, the result is undefined. +@end tex + @end deftypefun @deftypefun void mpz_pow_ui (mpz_t @var{rop}, mpz_t @var{base}, unsigned long int @var{exp}) @deftypefunx void mpz_ui_pow_ui (mpz_t @var{rop}, unsigned long int @var{base}, unsigned long int @var{exp}) -Set @var{rop} to @var{base} raised to @var{exp}. -@ifinfo -The case of 0^0 yields 1. -@end ifinfo -@iftex +@ifnottex +Set @var{rop} to @var{base} raised to @var{exp}. The case of 0^0 yields 1. +@end ifnottex @tex -The case of $0^0$ yields 1. +Set @var{rop} to $base^{exp}$. The case of $0^0$ yields 1. @end tex -@end iftex @end deftypefun -@subsection Square Root Functions +@need 2000 +@node Integer Roots, Number Theoretic Functions, Integer Exponentiation, Integer Functions +@section Root Extraction Functions +@cindex Integer root functions +@cindex Root extraction functions + +@deftypefun int mpz_root (mpz_t @var{rop}, mpz_t @var{op}, unsigned long int @var{n}) +@ifnottex +Set @var{rop} to the truncated integer part of the @var{n}th root of @var{op}. +@end ifnottex +@tex +Set @var{rop} to $\lfloor\root n \of {op}\rfloor$, the truncated integer +part of the @var{n}th root of @var{op}. +@end tex +Return non-zero if the computation was exact, i.e., if @var{op} is +@var{rop} to the @var{n}th power. +@end deftypefun + @deftypefun void mpz_sqrt (mpz_t @var{rop}, mpz_t @var{op}) -@ifinfo -Set @var{rop} to the truncated integer part of the square root of -@var{op}. -@end ifinfo -@iftex +@ifnottex +Set @var{rop} to the truncated integer part of the square root of @var{op}. +@end ifnottex @tex -Set @var{rop} to $\lfloor\sqrt{@var{op}}\rfloor$, the truncated integer -part of the square root of @var{op}. +Set @var{rop} to $\lfloor\sqrt{@var{op}}\rfloor$, the truncated integer part of +the square root of @var{op}. @end tex -@end iftex @end deftypefun @deftypefun void mpz_sqrtrem (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op}) -@ifinfo +@ifnottex Set @var{rop1} to the truncated integer part of the square root of @var{op}, like @code{mpz_sqrt}. Set @var{rop2} to @var{op}@minus{}@var{rop1}*@var{rop1}, -@end ifinfo -@iftex +@end ifnottex @tex Set @var{rop1} to $\lfloor\sqrt{@var{op}}\rfloor$, like @code{mpz_sqrt}. Set @var{rop2} to $(@var{op} - @var{rop1}^2)$, @end tex -@end iftex (i.e., zero if @var{op} is a perfect square). If @var{rop1} and @var{rop2} are the same variable, the results are undefined. @end deftypefun +@deftypefun int mpz_perfect_power_p (mpz_t @var{op}) +@ifnottex +Return non-zero if @var{op} is a perfect power, i.e., if there exist integers +@var{a} and @var{b}, with @var{b} > 1, such that @var{op} equals a raised to +b. Return zero otherwise. +@end ifnottex +@tex +Return non-zero if @var{op} is a perfect power, i.e., if there exist integers +$a$ and $b$, with $b>1$, such that $@var{op}=a^b$. Return zero otherwise. +@end tex +@end deftypefun + @deftypefun int mpz_perfect_square_p (mpz_t @var{op}) Return non-zero if @var{op} is a perfect square, i.e., if the square root of @var{op} is an integer. Return zero otherwise. @end deftypefun -@subsection Number Theoretic Functions -@deftypefun int mpz_probab_prime_p (mpz_t @var{op}, int @var{reps}) -@ifinfo -If this function returns 0, @var{op} is definitely not prime. If it returns -1, then @var{op} is `probably' prime. The probability of a false positive is -(1/4)**@var{reps}. -@end ifinfo -@iftex -@tex -If this function returns 0, @var{op} is definitely not prime. If it returns -1, then @var{op} is `probably' prime. The probability of a false positive is -$(1/4)^{{reps}}$. -@end tex -@end iftex -A reasonable value of reps is 25. +@need 2000 +@node Number Theoretic Functions, Integer Comparisons, Integer Roots, Integer Functions +@section Number Theoretic Functions +@cindex Number theoretic functions -An implementation of the probabilistic primality test found in Seminumerical -Algorithms (@pxref{References} Knuth). +@deftypefun int mpz_probab_prime_p (mpz_t @var{n}, int @var{reps}) +@cindex Prime testing functions +If this function returns 0, @var{n} is definitely not prime. If it +returns 1, then @var{n} is `probably' prime. If it returns 2, then +@var{n} is surely prime. Reasonable values of reps vary from 5 to 10; a +higher value lowers the probability for a non-prime to pass as a +`probable' prime. + +The function uses Miller-Rabin's probabilistic test. @end deftypefun +@deftypefun int mpz_nextprime (mpz_t @var{rop}, mpz_t @var{op}) +Set @var{rop} to the next prime greater than @var{op}. + +This function uses a probabilistic algorithm to identify primes, but for for +practical purposes it's adequate, since the chance of a composite passing will +be extremely small. +@end deftypefun + +@c mpz_prime_p not implemented as of gmp 3.0. + +@c @deftypefun int mpz_prime_p (mpz_t @var{n}) +@c Return non-zero if @var{n} is prime and zero if @var{n} is a non-prime. +@c This function is far slower than @code{mpz_probab_prime_p}, but then it +@c never returns non-zero for composite numbers. + +@c (For practical purposes, using @code{mpz_probab_prime_p} is adequate. +@c The likelihood of a programming error or hardware malfunction is orders +@c of magnitudes greater than the likelihood for a composite to pass as a +@c prime, if the @var{reps} argument is in the suggested range.) +@c @end deftypefun + @deftypefun void mpz_gcd (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) +@cindex Greatest common divisor functions Set @var{rop} to the greatest common divisor of @var{op1} and @var{op2}. +The result is always positive even if either of or both input operands +are negative. @end deftypefun @deftypefun {unsigned long int} mpz_gcd_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) Compute the greatest common divisor of @var{op1} and @var{op2}. If -@var{rop} is not NULL, store the result there. +@var{rop} is not @code{NULL}, store the result there. If the result is small enough to fit in an @code{unsigned long int}, it is returned. If the result does not fit, 0 is returned, and the result is equal @@ -1135,80 +1863,156 @@ is non-zero. @end deftypefun @deftypefun void mpz_gcdext (mpz_t @var{g}, mpz_t @var{s}, mpz_t @var{t}, mpz_t @var{a}, mpz_t @var{b}) +@cindex Extended GCD Compute @var{g}, @var{s}, and @var{t}, such that @var{a}@var{s} + -@var{b}@var{t} = @var{g} = @code{gcd} (@var{a}, @var{b}). If @var{t} is -NULL, that argument is not computed. +@var{b}@var{t} = @var{g} = @code{gcd}(@var{a}, @var{b}). If @var{t} is +@code{NULL}, that argument is not computed. @end deftypefun +@deftypefun void mpz_lcm (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) +@cindex Least common multiple functions +Set @var{rop} to the least common multiple of @var{op1} and @var{op2}. +@end deftypefun + @deftypefun int mpz_invert (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) +@cindex Modular inverse functions Compute the inverse of @var{op1} modulo @var{op2} and put the result in -@var{rop}. Return non-zero if an inverse exist, zero otherwise. When the -function returns zero, do not assume anything about the value in @var{rop}. +@var{rop}. Return non-zero if an inverse exists, zero otherwise. When the +function returns zero, @var{rop} is undefined. @end deftypefun @deftypefun int mpz_jacobi (mpz_t @var{op1}, mpz_t @var{op2}) @deftypefunx int mpz_legendre (mpz_t @var{op1}, mpz_t @var{op2}) -Compute the Jacobi and Legendre symbols, respectively. +@cindex Jabobi symbol functions +Compute the Jacobi and Legendre symbols, respectively. @var{op2} should be +odd and must be positive. @end deftypefun -@need 2000 -@node Comparison Functions, Integer Logic and Bit Fiddling, Integer Arithmetic, Integer Functions +@deftypefun int mpz_si_kronecker (long @var{a}, mpz_t @var{b}); +@deftypefunx int mpz_ui_kronecker (unsigned long @var{a}, mpz_t @var{b}); +@deftypefunx int mpz_kronecker_si (mpz_t @var{a}, long @var{b}); +@deftypefunx int mpz_kronecker_ui (mpz_t @var{a}, unsigned long @var{b}); +@cindex Kronecker symbol functions +@tex +Calculate the value of the Kronecker/Jacobi symbol $\left(a \over b\right)$, +with the Kronecker extension $\left(a \over 2\right) = \left(2 \over a\right)$ +when $a$ odd, or $\left(a \over 2\right) = 0$ when $a$ even. +@end tex +@ifnottex +Calculate the value of the Kronecker/Jacobi symbol (@var{a}/@var{b}), with the +Kronecker extension (a/2)=(2/a) when a odd, or (a/2)=0 when a even. +@end ifnottex +All values of @var{a} and @var{b} give a well-defined result. See Henri +Cohen, section 1.4.2, for more information (@pxref{References}). See also the +example program @file{demos/qcn.c} which uses @code{mpz_kronecker_ui}. +@end deftypefun + +@deftypefun {unsigned long int} mpz_remove (mpz_t @var{rop}, mpz_t @var{op}, mpz_t @var{f}) +Remove all occurrences of the factor @var{f} from @var{op} and store the +result in @var{rop}. Return the multiplicity of @var{f} in @var{op}. +@end deftypefun + +@deftypefun void mpz_fac_ui (mpz_t @var{rop}, unsigned long int @var{op}) +@cindex Factorial functions +Set @var{rop} to @var{op}!, the factorial of @var{op}. +@end deftypefun + +@deftypefun void mpz_bin_ui (mpz_t @var{rop}, mpz_t @var{n}, unsigned long int @var{k}) +@deftypefunx void mpz_bin_uiui (mpz_t @var{rop}, unsigned long int @var{n}, @w{unsigned long int @var{k}}) +@cindex Binomial coefficient functions +Compute the binomial coefficient +@ifnottex +@var{n} over @var{k} +@end ifnottex +@tex +$\left({n}\atop{k}\right)$ +@end tex +and store the result in @var{rop}. Negative values of @var{n} are supported +by @code{mpz_bin_ui}, using the identity +@ifnottex +bin(-n,k) = (-1)^k * bin(n+k-1,k) +@end ifnottex +@tex +$\left({-n}\atop{k}\right) = (-1)^k \left({n+k-1}\atop{k}\right)$ +@end tex +(see Knuth volume 1 section 1.2.6 part G). +@end deftypefun + +@deftypefun void mpz_fib_ui (mpz_t @var{rop}, unsigned long int @var{n}) +@cindex Fibonacci sequence functions +Compute the @var{n}th Fibonacci number and store the result in @var{rop}. +@end deftypefun + + +@node Integer Comparisons, Integer Logic and Bit Fiddling, Number Theoretic Functions, Integer Functions @comment node-name, next, previous, up @section Comparison Functions +@cindex Integer comparison functions +@cindex Comparison functions @deftypefun int mpz_cmp (mpz_t @var{op1}, mpz_t @var{op2}) -@ifinfo +@ifnottex Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} > @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} < @var{op2}. -@end ifinfo -@iftex +@end ifnottex @tex Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} > @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1} < @var{op2}$. @end tex -@end iftex @end deftypefun @deftypefn Macro int mpz_cmp_ui (mpz_t @var{op1}, unsigned long int @var{op2}) @deftypefnx Macro int mpz_cmp_si (mpz_t @var{op1}, signed long int @var{op2}) -@ifinfo +@ifnottex Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} > @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} < @var{op2}. -@end ifinfo -@iftex +@end ifnottex @tex Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} > @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1} < @var{op2}$. @end tex -@end iftex These functions are actually implemented as macros. They evaluate their arguments multiple times. @end deftypefn + +@deftypefun int mpz_cmpabs (mpz_t @var{op1}, mpz_t @var{op2}) +@deftypefunx int mpz_cmpabs_ui (mpz_t @var{op1}, unsigned long int @var{op2}) +@ifnottex +Compare the absolute values of @var{op1} and @var{op2}. Return a positive +value if @var{op1} > @var{op2}, zero if @var{op1} = @var{op2}, and a negative +value if @var{op1} < @var{op2}. +@end ifnottex +@tex +Compare the absolute values of @var{op1} and @var{op2}. Return a positive +value if $|@var{op1}| > |@var{op2}|$, zero if $|@var{op1}| = |@var{op2}|$, and a +negative value if $|@var{op1}| < |@var{op2}|$. +@end tex +@end deftypefun + @deftypefn Macro int mpz_sgn (mpz_t @var{op}) -@ifinfo +@ifnottex Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0. -@end ifinfo -@iftex +@end ifnottex @tex Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$. @end tex -@end iftex This function is actually implemented as a macro. It evaluates its arguments multiple times. @end deftypefn -@node Integer Logic and Bit Fiddling, I/O of Integers, Comparison Functions, Integer Functions +@node Integer Logic and Bit Fiddling, I/O of Integers, Integer Comparisons, Integer Functions @comment node-name, next, previous, up @section Logical and Bit Manipulation Functions @cindex Logical functions @cindex Bit manipulation functions +@cindex Integer bit manipulation functions These functions behave as if two's complement arithmetic were used (although sign-magnitude is used by the actual implementation). @@ -1221,9 +2025,9 @@ Set @var{rop} to @var{op1} logical-and @var{op2}. Set @var{rop} to @var{op1} inclusive-or @var{op2}. @end deftypefun -@c @deftypefun void mpz_xor (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) -@c Set @var{rop} to @var{op1} exclusive-or @var{op2}. -@c @end deftypefun +@deftypefun void mpz_xor (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) +Set @var{rop} to @var{op1} exclusive-or @var{op2}. +@end deftypefun @deftypefun void mpz_com (mpz_t @var{rop}, mpz_t @var{op}) Set @var{rop} to the one's complement of @var{op}. @@ -1242,7 +2046,7 @@ between the two operands. Otherwise, return the large It is possible to extend this function to return a useful value when the operands are both negative, but the current implementation returns @var{MAX_ULONG} in this case. @strong{Do not depend on this behavior, since -it will change in future versions of the library.} +it will change in a future release.} @end deftypefun @deftypefun {unsigned long int} mpz_scan0 (mpz_t @var{op}, unsigned long int @var{starting_bit}) @@ -1256,14 +2060,18 @@ bits, until the first set bit is found. Return the in @end deftypefun @deftypefun void mpz_setbit (mpz_t @var{rop}, unsigned long int @var{bit_index}) -Set bit @var{bit_index} in @var{op1}. +Set bit @var{bit_index} in @var{rop}. @end deftypefun @deftypefun void mpz_clrbit (mpz_t @var{rop}, unsigned long int @var{bit_index}) -Clear bit @var{bit_index} in @var{op1}. +Clear bit @var{bit_index} in @var{rop}. @end deftypefun -@node I/O of Integers, Miscellaneous Integer Functions, Integer Logic and Bit Fiddling, Integer Functions +@deftypefun int mpz_tstbit (mpz_t @var{op}, unsigned long int @var{bit_index}) +Check bit @var{bit_index} in @var{op} and return 0 or 1 accordingly. +@end deftypefun + +@node I/O of Integers, Integer Random Numbers, Integer Logic and Bit Fiddling, Integer Functions @comment node-name, next, previous, up @section Input and Output Functions @cindex Integer input and output functions @@ -1272,7 +2080,7 @@ Clear bit @var{bit_index} in @var{op1}. @cindex I/O functions Functions that perform input from a stdio stream, and functions that output to -a stdio stream. Passing a NULL pointer for a @var{stream} argument to any of +a stdio stream. Passing a @code{NULL} pointer for a @var{stream} argument to any of these functions will make them read from @code{stdin} and write to @code{stdout}, respectively. @@ -1324,15 +2132,74 @@ machines. @need 2000 -@node Miscellaneous Integer Functions,, I/O of Integers, Integer Functions +@node Integer Random Numbers, Miscellaneous Integer Functions, I/O of Integers, Integer Functions @comment node-name, next, previous, up -@section Miscellaneous Functions -@cindex Miscellaneous integer functions +@section Random Number Functions +@cindex Integer random number functions +@cindex Random number functions +The random number functions of GMP come in two groups; older function +that rely on a global state, and newer functions that accept a state +parameter that is read and modified. Please see the @ref{Random Number +Functions} for more information on how to use and not to use random +number functions. + +@deftypefun void mpz_urandomb (mpz_t @var{rop}, gmp_randstate_t @var{state}, +unsigned long int @var{n}) +Generate a uniformly distributed random integer in the range +@ifnottex +0 to 2^@var{n} @minus{} 1, +@end ifnottex +@tex +0 to $2^n-1$, +@end tex +inclusive. + +The variable @var{state} must be initialized by calling one of the +@code{gmp_randinit} functions (@ref{Random State Initialization}) before +invoking this function. +@end deftypefun + +@deftypefun void mpz_urandomm (mpz_t @var{rop}, gmp_randstate_t @var{state}, +mpz_t @var{n}) +Generate a uniform random integer in the range 0 to +@ifnottex +@var{n} @minus{} 1, inclusive. +@end ifnottex +@tex +$n-1$, inclusive. +@end tex + +The variable @var{state} must be initialized by calling one of the +@code{gmp_randinit} functions (@ref{Random State Initialization}) +before invoking this function. +@end deftypefun + +@deftypefun void mpz_rrandomb (mpz_t @var{rop}, gmp_randstate_t @var{state}, unsigned long int @var{n}) +Generate a random integer with long strings of zeros and ones in the +binary representation. Useful for testing functions and algorithms, +since this kind of random numbers have proven to be more likely to +trigger corner-case bugs. The random number will be in the range +@ifnottex +0 to 2^@var{n} @minus{} 1, +@end ifnottex +@tex +0 to $2^n-1$, +@end tex +inclusive. + +The variable @var{state} must be initialized by calling one of the +@code{gmp_randinit} functions (@ref{Random State Initialization}) +before invoking this function. +@end deftypefun + @deftypefun void mpz_random (mpz_t @var{rop}, mp_size_t @var{max_size}) Generate a random integer of at most @var{max_size} limbs. The generated random number doesn't satisfy any particular requirements of randomness. Negative random numbers are generated when @var{max_size} is negative. + +This function is obsolete. Use @code{mpz_urandomb} or +@code{mpz_urandomm} instead. @end deftypefun @deftypefun void mpz_random2 (mpz_t @var{rop}, mp_size_t @var{max_size}) @@ -1341,15 +2208,39 @@ of zeros and ones in the binary representation. Usefu and algorithms, since this kind of random numbers have proven to be more likely to trigger corner-case bugs. Negative random numbers are generated when @var{max_size} is negative. + +This function is obsolete. Use @code{mpz_rrandomb} instead. @end deftypefun + +@need 2000 +@node Miscellaneous Integer Functions, , Integer Random Numbers, Integer Functions +@comment node-name, next, previous, up +@section Miscellaneous Functions +@cindex Miscellaneous integer functions +@cindex Integer miscellaneous functions + +@deftypefun int mpz_fits_ulong_p (mpz_t @var{op}) +@deftypefunx int mpz_fits_slong_p (mpz_t @var{op}) +@deftypefunx int mpz_fits_uint_p (mpz_t @var{op}) +@deftypefunx int mpz_fits_sint_p (mpz_t @var{op}) +@deftypefunx int mpz_fits_ushort_p (mpz_t @var{op}) +@deftypefunx int mpz_fits_sshort_p (mpz_t @var{op}) +Return non-zero iff the value of @var{op} fits in an @code{unsigned long int}, +@code{signed long int}, @code{unsigned int}, @code{signed int}, @code{unsigned +short int}, or @code{signed short int}, respectively. Otherwise, return zero. +@end deftypefun + +@deftypefn Macro int mpz_odd_p (mpz_t @var{op}) +@deftypefnx Macro int mpz_even_p (mpz_t @var{op}) +Determine whether @var{op} is odd or even, respectively. Return non-zero if +yes, zero if no. These macros evaluate their arguments more than once. +@end deftypefn + @deftypefun size_t mpz_size (mpz_t @var{op}) Return the size of @var{op} measured in number of limbs. If @var{op} is zero, the returned value will be zero. @c (@xref{Nomenclature}, for an explanation of the concept @dfn{limb}.) - -@strong{This function is obsolete. It will disappear from future MP -releases.} @end deftypefun @deftypefun size_t mpz_sizeinbase (mpz_t @var{op}, int @var{base}) @@ -1369,7 +2260,7 @@ minus sign and one for the terminating '\0'). @chapter Rational Number Functions @cindex Rational number functions -This chapter describes the MP functions for performing arithmetic on rational +This chapter describes the GMP functions for performing arithmetic on rational numbers. These functions start with the prefix @code{mpq_}. Rational numbers are stored in objects of type @code{mpq_t}. @@ -1390,17 +2281,19 @@ Remove any factors that are common to the numerator an @end deftypefun @menu -* Initializing Rationals:: -* Assigning Rationals:: -* Simultaneous Integer Init & Assign:: -* Comparing Rationals:: -* Applying Integer Functions:: -* Miscellaneous Rational Functions:: +* Initializing Rationals:: +* Rational Arithmetic:: +* Comparing Rationals:: +* Applying Integer Functions:: +* I/O of Rationals:: +* Miscellaneous Rational Functions:: @end menu -@node Initializing Rationals, Assigning Rationals, Rational Number Functions, Rational Number Functions +@node Initializing Rationals, Rational Arithmetic, Rational Number Functions, Rational Number Functions @comment node-name, next, previous, up @section Initialization and Assignment Functions +@cindex Initialization and assignment functions +@cindex Rational init and assign @deftypefun void mpq_init (mpq_t @var{dest_rational}) Initialize @var{dest_rational} and set it to 0/1. Each variable should @@ -1425,9 +2318,16 @@ Set the value of @var{rop} to @var{op1}/@var{op2}. No @code{mpq_canonicalize} before any operations are performed on @var{rop}. @end deftypefun -@node Assigning Rationals, Comparing Rationals, Initializing Rationals, Rational Number Functions +@deftypefun void mpq_swap (mpq_t @var{rop1}, mpq_t @var{rop2}) +Swap the values @var{rop1} and @var{rop2} efficiently. +@end deftypefun + + +@node Rational Arithmetic, Comparing Rationals, Initializing Rationals, Rational Number Functions @comment node-name, next, previous, up @section Arithmetic Functions +@cindex Rational arithmetic functions +@cindex Arithmetic functions @deftypefun void mpq_add (mpq_t @var{sum}, mpq_t @var{addend1}, mpq_t @var{addend2}) Set @var{sum} to @var{addend1} + @var{addend2}. @@ -1438,17 +2338,16 @@ Set @var{difference} to @var{minuend} @minus{} @var{su @end deftypefun @deftypefun void mpq_mul (mpq_t @var{product}, mpq_t @var{multiplier}, mpq_t @var{multiplicand}) -@ifinfo +@ifnottex Set @var{product} to @var{multiplier} times @var{multiplicand}. -@end ifinfo -@iftex +@end ifnottex @tex Set @var{product} to $@var{multiplier} \times @var{multiplicand}$. @end tex -@end iftex @end deftypefun @deftypefun void mpq_div (mpq_t @var{quotient}, mpq_t @var{dividend}, mpq_t @var{divisor}) +@cindex Division functions Set @var{quotient} to @var{dividend}/@var{divisor}. @end deftypefun @@ -1461,42 +2360,40 @@ Set @var{inverted_number} to 1/@var{number}. If the n zero, this routine will divide by zero. @end deftypefun -@node Comparing Rationals, Applying Integer Functions, Assigning Rationals, Rational Number Functions +@node Comparing Rationals, Applying Integer Functions, Rational Arithmetic, Rational Number Functions @comment node-name, next, previous, up @section Comparison Functions +@cindex Rational comparison functions +@cindex Comparison functions @deftypefun int mpq_cmp (mpq_t @var{op1}, mpq_t @var{op2}) -@ifinfo +@ifnottex Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} > @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} < @var{op2}. -@end ifinfo -@iftex +@end ifnottex @tex Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} > @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1} < @var{op2}$. @end tex -@end iftex To determine if two rationals are equal, @code{mpq_equal} is faster than @code{mpq_cmp}. @end deftypefun @deftypefn Macro int mpq_cmp_ui (mpq_t @var{op1}, unsigned long int @var{num2}, unsigned long int @var{den2}) -@ifinfo +@ifnottex Compare @var{op1} and @var{num2}/@var{den2}. Return a positive value if @var{op1} > @var{num2}/@var{den2}, zero if @var{op1} = @var{num2}/@var{den2}, and a negative value if @var{op1} < @var{num2}/@var{den2}. -@end ifinfo -@iftex +@end ifnottex @tex Compare @var{op1} and @var{num2}/@var{den2}. Return a positive value if $@var{op1} > @var{num2}/@var{den2}$, zero if $@var{op1} = @var{num2}/@var{den2}$, and a negative value if $@var{op1} < @var{num2}/@var{den2}$. @end tex -@end iftex This routine allows that @var{num2} and @var{den2} have common factors. @@ -1505,14 +2402,12 @@ arguments multiple times. @end deftypefn @deftypefn Macro int mpq_sgn (mpq_t @var{op}) -@ifinfo +@ifnottex Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0. -@end ifinfo -@iftex +@end ifnottex @tex Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$. @end tex -@end iftex This function is actually implemented as a macro. It evaluates its arguments multiple times. @@ -1524,11 +2419,13 @@ non-equal. Although @code{mpq_cmp} can be used for th function is much faster. @end deftypefun -@node Applying Integer Functions, Miscellaneous Rational Functions, Comparing Rationals, Rational Number Functions +@node Applying Integer Functions, I/O of Rationals, Comparing Rationals, Rational Number Functions @comment node-name, next, previous, up @section Applying Integer Functions to Rationals +@cindex Rational numerator and denominator +@cindex Numerator and denominator -The set of @code{mpq} functions is quite small. In particular, there are no +The set of @code{mpq} functions is quite small. In particular, there are few functions for either input or output. But there are two macros that allow us to apply any @code{mpz} function on the numerator or denominator of a rational number. If these macros are used to assign to the rational number, @@ -1540,15 +2437,49 @@ Return a reference to the numerator and denominator of The @code{mpz} functions can be used on the result of these macros. @end deftypefn + @need 2000 -@node Miscellaneous Rational Functions, , Applying Integer Functions, Rational Number Functions +@node I/O of Rationals, Miscellaneous Rational Functions, Applying Integer Functions, Rational Number Functions @comment node-name, next, previous, up +@section Input and Output Functions +@cindex Rational input and output functions +@cindex Input functions +@cindex Output functions +@cindex I/O functions + +Functions that perform input from a stdio stream, and functions that output to +a stdio stream. Passing a @code{NULL} pointer for a @var{stream} argument to +any of these functions will make them read from @code{stdin} and write to +@code{stdout}, respectively. + +When using any of these functions, it is a good idea to include @file{stdio.h} +before @file{gmp.h}, since that will allow @file{gmp.h} to define prototypes +for these functions. + +@deftypefun size_t mpq_out_str (FILE *@var{stream}, int @var{base}, mpq_t @var{op}) +Output @var{op} on stdio stream @var{stream}, as a string of digits in base +@var{base}. The base may vary from 2 to 36. Output is in the form +@samp{num/den} or if the denominator is 1 then just @samp{num}. + +Return the number of bytes written, or if an error occurred, return 0. +@end deftypefun + + +@need 2000 +@node Miscellaneous Rational Functions, , I/O of Rationals, Rational Number Functions +@comment node-name, next, previous, up @section Miscellaneous Functions +@cindex Rational miscellaneous functions +@cindex Miscellaneous rational functions @deftypefun double mpq_get_d (mpq_t @var{op}) Convert @var{op} to a double. @end deftypefun +@deftypefun double mpq_set_d (mpq_t @var{rop}, double @var{d}) +Set @var{rop} to the value of d, without rounding. +@end deftypefun + These functions assign between either the numerator or denominator of a rational, and an integer. Instead of using these functions, it is preferable to use the more general mechanisms @code{mpq_numref} and @code{mpq_denref}, @@ -1600,50 +2531,53 @@ This function is equivalent to @cindex Floating-point functions @cindex Float functions -This is a description of the @emph{preliminary} interface for floating-point -arithmetic in GNU MP 2. +This chapter describes the GMP functions for performing floating point +arithmetic. These functions start with the prefix @code{mpf_}. -The floating-point functions expect arguments of type @code{mpf_t}. +GMP floating point numbers are stored in objects of type @code{mpf_t}. -The MP floating-point functions have an interface that is similar to the MP +The GMP floating-point functions have an interface that is similar to the GMP integer functions. The function prefix for floating-point operations is @code{mpf_}. There is one significant characteristic of floating-point numbers that has -motivated a difference between this function class and other MP function +motivated a difference between this function class and other GMP function classes: the inherent inexactness of floating point arithmetic. The user has to specify the precision of each variable. A computation that assigns a variable will take place with the precision of the assigned variable; the precision of variables used as input is ignored. @cindex User-defined precision +@cindex Precision of floats The precision of a calculation is defined as follows: Compute the requested operation exactly (with ``infinite precision''), and truncate the result to the destination variable precision. Even if the user has asked for a very -high precision, MP will not calculate with superfluous digits. For example, +high precision, GMP will not calculate with superfluous digits. For example, if two low-precision numbers of nearly equal magnitude are added, the precision of the result will be limited to what is required to represent the result accurately. -The MP floating-point functions are @emph{not} intended as a smooth extension +The GMP floating-point functions are @emph{not} intended as a smooth extension to the IEEE P754 arithmetic. Specifically, the results obtained on one computer often differs from the results obtained on a computer with a different word size. @menu -* Initializing Floats:: -* Assigning Floats:: -* Simultaneous Float Init & Assign:: -* Converting Floats:: -* Float Arithmetic:: -* Float Comparison:: -* I/O of Floats:: -* Miscellaneous Float Functions:: +* Initializing Floats:: +* Assigning Floats:: +* Simultaneous Float Init & Assign:: +* Converting Floats:: +* Float Arithmetic:: +* Float Comparison:: +* I/O of Floats:: +* Miscellaneous Float Functions:: @end menu -@node Initializing Floats, Assigning Floats, , Floating-point Functions +@node Initializing Floats, Assigning Floats, Floating-point Functions, Floating-point Functions @comment node-name, next, previous, up -@section Initialization and Assignment Functions +@section Initialization Functions +@cindex Float initialization functions +@cindex Initialization functions @deftypefun void mpf_set_default_prec (unsigned long int @var{prec}) Set the default precision to be @strong{at least} @var{prec} bits. All @@ -1707,14 +2641,17 @@ Set the precision of @var{rop} to be @strong{at least} is a low-level function that does not change the allocation. The @var{prec} argument must not be larger that the precision previously returned by @code{mpf_get_prec}. It is crucial that the precision of @var{rop} is -ultimately reset to exactly the value returned by @code{mpf_get_prec}. +ultimately reset to exactly the value returned by @code{mpf_get_prec} before +the first call to @code{mpf_set_prec_raw}. @end deftypefun +@need 2000 @node Assigning Floats, Simultaneous Float Init & Assign, Initializing Floats, Floating-point Functions @comment node-name, next, previous, up -@subsection Assignment Functions +@section Assignment Functions @cindex Float assignment functions +@cindex Assignment functions These functions assign new values to already initialized floats (@pxref{Initializing Floats}). @@ -1743,19 +2680,30 @@ Unlike the corresponding @code{mpz} function, the base from the leading characters of the string if @var{base} is 0. This is so that numbers like @samp{0.23} are not interpreted as octal. -White space is allowed in the string, and is simply ignored. +White space is allowed in the string, and is simply ignored. [This is not +really true; white-space is ignored in the beginning of the string and within +the mantissa, but not in other places, such as after a minus sign or in the +exponent. We are considering changing the definition of this function, making +it fail when there is any white-space in the input, since that makes a lot of +sense. Please tell us your opinion about this change. Do you really want it +to accept "3 14" as meaning 314 as it does now?] This function returns 0 if the entire string up to the '\0' is a valid number in base @var{base}. Otherwise it returns @minus{}1. @end deftypefun +@deftypefun void mpf_swap (mpf_t @var{rop1}, mpf_t @var{rop2}) +Swap the values @var{rop1} and @var{rop2} efficiently. +@end deftypefun + @node Simultaneous Float Init & Assign, Converting Floats, Assigning Floats, Floating-point Functions @comment node-name, next, previous, up -@subsection Combined Initialization and Assignment Functions +@section Combined Initialization and Assignment Functions @cindex Initialization and assignment functions +@cindex Float init and assign functions -For convenience, MP provides a parallel series of initialize-and-set functions +For convenience, GMP provides a parallel series of initialize-and-set functions which initialize the output and then store the value there. These functions' names have the form @code{mpf_init_set@dots{}} @@ -1789,6 +2737,7 @@ set by @code{mpf_set_default_prec}. @node Converting Floats, Float Arithmetic, Simultaneous Float Init & Assign, Floating-point Functions @comment node-name, next, previous, up @section Conversion Functions +@cindex Float conversion functions @cindex Conversion functions @deftypefun double mpf_get_d (mpf_t @var{op}) @@ -1801,10 +2750,10 @@ from 2 to 36. Generate at most @var{n_digits} signifi @var{n_digits} is 0, the maximum number of digits accurately representable by @var{op}. -If @var{str} is NULL, space for the mantissa is allocated using the default -allocation function, and a pointer to the string is returned. +If @var{str} is @code{NULL}, space for the mantissa is allocated using the default +allocation function. -If @var{str} is not NULL, it should point to a block of storage enough large +If @var{str} is not @code{NULL}, it should point to a block of storage enough large for the mantissa, i.e., @var{n_digits} + 2. The two extra bytes are for a possible minus sign, and for the terminating null character. @@ -1813,12 +2762,15 @@ The exponent is written through the pointer @var{exppt If @var{n_digits} is 0, the maximum number of digits meaningfully achievable from the precision of @var{op} will be generated. Note that the space requirements for @var{str} in this case will be impossible for the user to -predetermine. Therefore, you need to pass NULL for the string argument +predetermine. Therefore, you need to pass @code{NULL} for the string argument whenever @var{n_digits} is 0. The generated string is a fraction, with an implicit radix point immediately to the left of the first digit. For example, the number 3.1416 would be returned as "31416" in the string and 1 written at @var{expptr}. + +A pointer to the result string is returned. This pointer will will either +equal @var{str}, or if that is @code{NULL}, will point to the allocated storage. @end deftypefun @@ -1830,14 +2782,12 @@ returned as "31416" in the string and 1 written at @va @deftypefun void mpf_add (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2}) @deftypefunx void mpf_add_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2}) -@ifinfo +@ifnottex Set @var{rop} to @var{op1} + @var{op2}. -@end ifinfo -@iftex +@end ifnottex @tex Set @var{rop} to $@var{op1} + @var{op2}$. @end tex -@end iftex @end deftypefun @deftypefun void mpf_sub (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2}) @@ -1848,42 +2798,46 @@ Set @var{rop} to @var{op1} @minus{} @var{op2}. @deftypefun void mpf_mul (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2}) @deftypefunx void mpf_mul_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2}) -@ifinfo +@ifnottex Set @var{rop} to @var{op1} times @var{op2}. -@end ifinfo -@iftex +@end ifnottex @tex Set @var{rop} to $@var{op1} \times @var{op2}$. @end tex -@end iftex @end deftypefun Division is undefined if the divisor is zero, and passing a zero divisor to the divide functions will make these functions intentionally divide by zero. -This gives the user the possibility to handle arithmetic exceptions in these -functions in the same manner as other arithmetic exceptions. +This lets the user handle arithmetic exceptions in these functions in the same +manner as other arithmetic exceptions. @deftypefun void mpf_div (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2}) @deftypefunx void mpf_ui_div (mpf_t @var{rop}, unsigned long int @var{op1}, mpf_t @var{op2}) @deftypefunx void mpf_div_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2}) +@cindex Division functions Set @var{rop} to @var{op1}/@var{op2}. @end deftypefun @deftypefun void mpf_sqrt (mpf_t @var{rop}, mpf_t @var{op}) @deftypefunx void mpf_sqrt_ui (mpf_t @var{rop}, unsigned long int @var{op}) -@ifinfo +@cindex Root extraction functions +@ifnottex Set @var{rop} to the square root of @var{op}. -@end ifinfo -@iftex +@end ifnottex @tex Set @var{rop} to $\sqrt{@var{op}}$. @end tex -@end iftex @end deftypefun -@c @deftypefun void mpf_pow_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2}) -@c Set @var{rop} to @var{op1} raised to @var{op2}. -@c @end deftypefun +@deftypefun void mpf_pow_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2}) +@cindex Exponentiation functions +@ifnottex +Set @var{rop} to @var{op1} raised to the power @var{op2}. +@end ifnottex +@tex +Set @var{rop} to $@var{op1}^{op2}$. +@end tex +@end deftypefun @deftypefun void mpf_neg (mpf_t @var{rop}, mpf_t @var{op}) Set @var{rop} to @minus{}@var{op}. @@ -1894,48 +2848,42 @@ Set @var{rop} to the absolute value of @var{op}. @end deftypefun @deftypefun void mpf_mul_2exp (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2}) -@ifinfo +@ifnottex Set @var{rop} to @var{op1} times 2 raised to @var{op2}. -@end ifinfo -@iftex +@end ifnottex @tex Set @var{rop} to $@var{op1} \times 2^{op2}$. @end tex -@end iftex @end deftypefun @deftypefun void mpf_div_2exp (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2}) -@ifinfo +@ifnottex Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}. -@end ifinfo -@iftex +@end ifnottex @tex Set @var{rop} to $@var{op1}/2^{op2}$. @end tex -@end iftex @end deftypefun @node Float Comparison, I/O of Floats, Float Arithmetic, Floating-point Functions @comment node-name, next, previous, up @section Comparison Functions -@cindex Float comparisons functions +@cindex Float comparison functions @cindex Comparison functions @deftypefun int mpf_cmp (mpf_t @var{op1}, mpf_t @var{op2}) @deftypefunx int mpf_cmp_ui (mpf_t @var{op1}, unsigned long int @var{op2}) @deftypefunx int mpf_cmp_si (mpf_t @var{op1}, signed long int @var{op2}) -@ifinfo +@ifnottex Compare @var{op1} and @var{op2}. Return a positive value if @var{op1} > @var{op2}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} < @var{op2}. -@end ifinfo -@iftex +@end ifnottex @tex Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} > @var{op2}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1} < @var{op2}$. @end tex -@end iftex @end deftypefun @deftypefun int mpf_eq (mpf_t @var{op1}, mpf_t @var{op2}, unsigned long int op3) @@ -1950,14 +2898,12 @@ result in @var{rop}. @end deftypefun @deftypefn Macro int mpf_sgn (mpf_t @var{op}) -@ifinfo +@ifnottex Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0. -@end ifinfo -@iftex +@end ifnottex @tex Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$. @end tex -@end iftex This function is actually implemented as a macro. It evaluates its arguments multiple times. @@ -1972,7 +2918,7 @@ arguments multiple times. @cindex I/O functions Functions that perform input from a stdio stream, and functions that output to -a stdio stream. Passing a NULL pointer for a @var{stream} argument to any of +a stdio stream. Passing a @code{NULL} pointer for a @var{stream} argument to any of these functions will make them read from @code{stdin} and write to @code{stdout}, respectively. @@ -2026,11 +2972,29 @@ Return the number of bytes read, or if an error occurr @c @end deftypefun -@node Miscellaneous Float Functions, , I/O of Floats, Floating-point Functions +@node Miscellaneous Float Functions, , I/O of Floats, Floating-point Functions @comment node-name, next, previous, up @section Miscellaneous Functions @cindex Miscellaneous float functions +@cindex Float miscellaneous functions +@deftypefun void mpf_ceil (mpf_t @var{rop}, mpf_t @var{op}) +@deftypefunx void mpf_floor (mpf_t @var{rop}, mpf_t @var{op}) +@deftypefunx void mpf_trunc (mpf_t @var{rop}, mpf_t @var{op}) +Set @var{rop} to @var{op} rounded to an integer. @code{mpf_ceil} rounds to +the next higher integer, @code{mpf_floor} to the next lower, and +@code{mpf_trunc} to the integer towards zero. +@end deftypefun + +@deftypefun void mpf_urandomb (mpf_t @var{rop}, gmp_randstate_t @var{state}, unsigned long int @var{nbits}) +Generate a uniformly distributed random float in @var{rop}, such that 0 <= +@var{rop} < 1, with @var{nbits} significant bits in the mantissa. + +The variable @var{state} must be initialized by calling one of the +@code{gmp_randinit} functions (@ref{Random State Initialization}) +before invoking this function. +@end deftypefun + @deftypefun void mpf_random2 (mpf_t @var{rop}, mp_size_t @var{max_size}, mp_exp_t @var{max_exp}) Generate a random float of at most @var{max_size} limbs, with long strings of zeros and ones in the binary representation. The exponent of the number is in @@ -2040,22 +3004,24 @@ proven to be more likely to trigger corner-case bugs. are generated when @var{max_size} is negative. @end deftypefun + + @c @deftypefun size_t mpf_size (mpf_t @var{op}) @c Return the size of @var{op} measured in number of limbs. If @var{op} is @c zero, the returned value will be zero. (@xref{Nomenclature}, for an @c explanation of the concept @dfn{limb}.) @c -@c @strong{This function is obsolete. It will disappear from future MP +@c @strong{This function is obsolete. It will disappear from future GMP @c releases.} @c @end deftypefun -@node Low-level Functions, BSD Compatible Functions, Floating-point Functions, Top +@node Low-level Functions, Random Number Functions, Floating-point Functions, Top @comment node-name, next, previous, up @chapter Low-level Functions @cindex Low-level functions -This chapter describes low-level MP functions, used to implement the high-level -MP functions, but also intended for time-critical user code. +This chapter describes low-level GMP functions, used to implement the high-level +GMP functions, but also intended for time-critical user code. These functions start with the prefix @code{mpn_}. @@ -2077,136 +3043,157 @@ With this way of specifying operands, it is possible t on subranges of an argument, and store the result into a subrange of a destination. -A common requirement for all functions is that each source area needs at least -one limb. No size argument may be zero. +A common requirement for all functions is that each source area needs at +least one limb. No size argument may be zero. Unless otherwise stated, +in-place operations are allowed where source and destination are the +same, but not where they only partly overlap. -The @code{mpn} functions is the base for the implementation of the @code{mpz_}, -@code{mpf_}, and @code{mpq_} functions. +The @code{mpn} functions are the base for the implementation of the +@code{mpz_}, @code{mpf_}, and @code{mpq_} functions. -This example adds the number beginning at @var{src1_ptr} and the number -beginning at @var{src2_ptr} and writes the sum at @var{dest_ptr}. All areas +This example adds the number beginning at @var{s1p} and the number +beginning at @var{s2p} and writes the sum at @var{destp}. All areas have @var{size} limbs. @example -cy = mpn_add_n (dest_ptr, src1_ptr, src2_ptr, size) +cy = mpn_add_n (destp, s1p, s2p, size) @end example @noindent In the notation used here, a source operand is identified by the pointer to the least significant limb, and the limb count in braces. For example, -@{s1_ptr, s1_size@}. +@{s1p, s1size@}. -@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}) -Add @{@var{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@}, and -write the @var{size} least significant limbs of the result to @var{dest_ptr}. +@deftypefun mp_limb_t mpn_add_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{size}) +Add @{@var{s1p}, @var{size}@} and @{@var{s2p}, @var{size}@}, and +write the @var{size} least significant limbs of the result to @var{rp}. Return carry, either 0 or 1. This is the lowest-level function for addition. It is the preferred function for addition, since it is written in assembly for most targets. For addition -of a variable to itself (i.e., @var{src1_ptr} equals @var{src2_ptr}, use +of a variable to itself (i.e., @var{s1p} equals @var{s2p}, use @code{mpn_lshift} with a count of 1 for optimal speed. @end deftypefun -@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}) -Add @{@var{src1_ptr}, @var{size}@} and @var{src2_limb}, and write the -@var{size} least significant limbs of the result to @var{dest_ptr}. Return +@deftypefun mp_limb_t mpn_add_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{size}, mp_limb_t @var{s2limb}) +Add @{@var{s1p}, @var{size}@} and @var{s2limb}, and write the +@var{size} least significant limbs of the result to @var{rp}. Return carry, either 0 or 1. @end deftypefun -@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}) -Add @{@var{src1_ptr}, @var{src1_size}@} and @{@var{src2_ptr}, -@var{src2_size}@}, and write the @var{src1_size} least significant limbs of -the result to @var{dest_ptr}. Return carry, either 0 or 1. +@deftypefun mp_limb_t mpn_add (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, const mp_limb_t *@var{s2p}, mp_size_t @var{s2size}) +Add @{@var{s1p}, @var{s1size}@} and @{@var{s2p}, +@var{s2size}@}, and write the @var{s1size} least significant limbs of +the result to @var{rp}. Return carry, either 0 or 1. -This function requires that @var{src1_size} is greater than or equal to -@var{src2_size}. +This function requires that @var{s1size} is greater than or equal to +@var{s2size}. @end deftypefun -@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}) -Subtract @{@var{src2_ptr}, @var{src2_size}@} from @{@var{src1_ptr}, +@deftypefun mp_limb_t mpn_sub_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{size}) +Subtract @{@var{s2p}, @var{s2size}@} from @{@var{s1p}, @var{size}@}, and write the @var{size} least significant limbs of the result -to @var{dest_ptr}. Return borrow, either 0 or 1. +to @var{rp}. Return borrow, either 0 or 1. This is the lowest-level function for subtraction. It is the preferred function for subtraction, since it is written in assembly for most targets. @end deftypefun -@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}) -Subtract @var{src2_limb} from @{@var{src1_ptr}, @var{size}@}, and write the -@var{size} least significant limbs of the result to @var{dest_ptr}. Return +@deftypefun mp_limb_t mpn_sub_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{size}, mp_limb_t @var{s2limb}) +Subtract @var{s2limb} from @{@var{s1p}, @var{size}@}, and write the +@var{size} least significant limbs of the result to @var{rp}. Return borrow, either 0 or 1. @end deftypefun -@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}) -Subtract @{@var{src2_ptr}, @var{src2_size}@} from @{@var{src1_ptr}, -@var{src1_size}@}, and write the @var{src1_size} least significant limbs of -the result to @var{dest_ptr}. Return borrow, either 0 or 1. +@deftypefun mp_limb_t mpn_sub (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, const mp_limb_t *@var{s2p}, mp_size_t @var{s2size}) +Subtract @{@var{s2p}, @var{s2size}@} from @{@var{s1p}, +@var{s1size}@}, and write the @var{s1size} least significant limbs of +the result to @var{rp}. Return borrow, either 0 or 1. -This function requires that @var{src1_size} is greater than or equal to -@var{src2_size}. +This function requires that @var{s1size} is greater than or equal to +@var{s2size}. @end deftypefun -@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}) -Multiply @{@var{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@}, -and write the @strong{entire} result to @var{dest_ptr}. +@deftypefun void mpn_mul_n (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{size}) +Multiply @{@var{s1p}, @var{size}@} and @{@var{s2p}, @var{size}@}, +and write the @strong{entire} result to @var{rp}. -The destination has to have space for 2@var{size} limbs, even if the +The destination has to have space for 2*@var{size} limbs, even if the significant result might be one limb smaller. @end deftypefun -@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}) -Multiply @{@var{src1_ptr}, @var{size}@} and @var{src2_limb}, and write the -@var{size} least significant limbs of the product to @var{dest_ptr}. Return +@deftypefun mp_limb_t mpn_mul_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{size}, mp_limb_t @var{s2limb}) +Multiply @{@var{s1p}, @var{size}@} and @var{s2limb}, and write the +@var{size} least significant limbs of the product to @var{rp}. Return the most significant limb of the product. This is a low-level function that is a building block for general -multiplication as well as other operations in MP. It is written in assembly +multiplication as well as other operations in GMP. It is written in assembly for most targets. -Don't call this function if @var{src2_limb} is a power of 2; use -@code{mpn_lshift} with a count equal to the logarithm of @var{src2_limb} +Don't call this function if @var{s2limb} is a power of 2; use +@code{mpn_lshift} with a count equal to the logarithm of @var{s2limb} instead, for optimal speed. @end deftypefun -@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}) -Multiply @{@var{src1_ptr}, @var{size}@} and @var{src2_limb}, and add the -@var{size} least significant limbs of the product to @{@var{dest_ptr}, -@var{size}@} and write the result to @var{dest_ptr} @var{dest_ptr}. Return +@deftypefun mp_limb_t mpn_addmul_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{size}, mp_limb_t @var{s2limb}) +Multiply @{@var{s1p}, @var{size}@} and @var{s2limb}, and add the +@var{size} least significant limbs of the product to @{@var{rp}, +@var{size}@} and write the result to @var{rp}. Return the most significant limb of the product, plus carry-out from the addition. This is a low-level function that is a building block for general -multiplication as well as other operations in MP. It is written in assembly +multiplication as well as other operations in GMP. It is written in assembly for most targets. @end deftypefun -@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}) -Multiply @{@var{src1_ptr}, @var{size}@} and @var{src2_limb}, and subtract the -@var{size} least significant limbs of the product from @{@var{dest_ptr}, -@var{size}@} and write the result to @var{dest_ptr}. Return the most +@deftypefun mp_limb_t mpn_submul_1 (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{size}, mp_limb_t @var{s2limb}) +Multiply @{@var{s1p}, @var{size}@} and @var{s2limb}, and subtract the +@var{size} least significant limbs of the product from @{@var{rp}, +@var{size}@} and write the result to @var{rp}. Return the most significant limb of the product, minus borrow-out from the subtraction. This is a low-level function that is a building block for general -multiplication and division as well as other operations in MP. It is written +multiplication and division as well as other operations in GMP. It is written in assembly for most targets. @end deftypefun -@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}) -Multiply @{@var{src1_ptr}, @var{src1_size}@} and @{@var{src2_ptr}, -@var{src2_size}@}, and write the result to @var{dest_ptr}. Return the most +@deftypefun mp_limb_t mpn_mul (mp_limb_t *@var{rp}, const mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, const mp_limb_t *@var{s2p}, mp_size_t @var{s2size}) +Multiply @{@var{s1p}, @var{s1size}@} and @{@var{s2p}, +@var{s2size}@}, and write the result to @var{rp}. Return the most significant limb of the result. -The destination has to have space for @var{src1_size} + @var{src1_size} +The destination has to have space for @var{s1size} + @var{s2size} limbs, even if the result might be one limb smaller. -This function requires that @var{src1_size} is greater than or equal to -@var{src2_size}. The destination must be distinct from either input operands. +This function requires that @var{s1size} is greater than or equal to +@var{s2size}. The destination must be distinct from either input operands. @end deftypefun -@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}) -Divide @{@var{rs2p}, @var{rs2size}@} by @{@var{s3p}, @var{s3size}@}, and -write the quotient at @var{r1p}, with the exception of the most significant -limb, which is returned. The remainder replaces the dividend at @var{rs2p}. +@deftypefun mp_limb_t mpn_tdiv_qr (mp_limb_t *@var{qp}, mp_limb_t *@var{rp}, mp_size_t @var{qxn}, const mp_limb_t *@var{np}, mp_size_t @var{nn}, const mp_limb_t *@var{dp}, mp_size_t @var{dn}) +Divide @{@var{np}, @var{nn}@} by @{@var{dp}, @var{dn}@}. Write the quotient +at @var{qp} and the remainder at @var{rp}. +The quotient written at @var{qp} will be @var{nn} @minus{} @var{dn} + 1 limbs. +The remainder written at @var{rp} will be @var{dn} limbs. + +It is required that @var{nn} is greater than or equal to @var{dn}. The +@var{qxn} operand must be zero. + +The quotient is rounded towards 0. + +No overlap between arguments is permitted. +@end deftypefun + +@deftypefun mp_limb_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}) +[This function is obsolete. Please call @code{mpn_tdiv_qr} instead for +best performance.] + +Divide @{@var{rs2p}, @var{rs2size}@} by @{@var{s3p}, @var{s3size}@}, and write +the quotient at @var{r1p}, with the exception of the most significant limb, +which is returned. The remainder replaces the dividend at @var{rs2p}; it will +be @var{s3size} limbs long (i.e., as many limbs as the divisor). + In addition to an integer quotient, @var{xsize} fraction limbs are developed, and stored after the integral limbs. For most usages, @var{xsize} will be zero. @@ -2223,43 +3210,93 @@ The area at @var{r1p} needs to be @var{rs2size} @minus @var{xsize} limbs large. @end deftypefun -@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}) +@deftypefn Function mp_limb_t mpn_divrem_1 (mp_limb_t *@var{r1p}, mp_size_t @var{xsize}, @w{mp_limb_t *@var{s2p}}, mp_size_t @var{s2size}, mp_limb_t @var{s3limb}) +@deftypefnx Macro mp_limb_t mpn_divmod_1 (mp_limb_t *@var{r1p}, mp_limb_t *@var{s2p}, @w{mp_size_t @var{s2size}}, @w{mp_limb_t @var{s3limb}}) Divide @{@var{s2p}, @var{s2size}@} by @var{s3limb}, and write the quotient at @var{r1p}. Return the remainder. -In addition to an integer quotient, @var{xsize} fraction limbs are developed, -and stored after the integral limbs. For most usages, @var{xsize} will be -zero. +The integer quotient is written to @{@var{r1p}+@var{xsize}, @var{s2size}@} and +in addition @var{xsize} fraction limbs are developed and written to +@{@var{r1p}, @var{xsize}@}. Either or both @var{s2size} and @var{xsize} can +be zero. For most usages, @var{xsize} will be zero. +@code{mpn_divmod_1} exists for upward source compatibility and is simply a +macro calling @code{mpn_divrem_1} with an @var{xsize} of 0. + The areas at @var{r1p} and @var{s2p} have to be identical or completely separate, not partially overlapping. -@end deftypefun +@end deftypefn -@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}) +@deftypefun mp_limb_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}) @strong{This interface is obsolete. It will disappear from future releases. Use @code{mpn_divrem} in its stead.} @end deftypefun -@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}) -@strong{This interface is obsolete. It will disappear from future releases. -Use @code{mpn_divrem_1} in its stead.} -@end deftypefun +@deftypefn Macro mp_limb_t mpn_divexact_by3 (mp_limb_t *@var{rp}, mp_limb_t *@var{sp}, @w{mp_size_t @var{size}}) +@deftypefnx Function mp_limb_t mpn_divexact_by3c (mp_limb_t *@var{rp}, mp_limb_t *@var{sp}, @w{mp_size_t @var{size}}, mp_limb_t @var{carry}) +Divide @{@var{sp}, @var{size}@} by 3, expecting it to divide exactly, and +writing the result to @{@var{rp}, @var{size}@}. If 3 divides exactly, the +return value is zero and the result is the quotient. If not, the return value +is non-zero and the result won't be anything useful. -@deftypefun mp_limb_t mpn_mod_1 (mp_limb_t * @var{s1p}, mp_size_t @var{s1size}, mp_limb_t @var{s2limb}) +@code{mpn_divexact_by3c} takes an initial carry parameter, which can be the +return value from a previous call, so a large calculation can be done piece by +piece. @code{mpn_divexact_by3} is simply a macro calling +@code{mpn_divexact_by3c} with a 0 carry parameter. + +These routines use a multiply-by-inverse and will be faster than +@code{mpn_divrem_1} on CPUs with fast multiplication but slow division. + +The source @math{a}, result @math{q}, size @math{n}, initial carry @math{i}, +and return value @math{c} satisfy +@tex +$c b^n + a - i = 3q$, +@end tex +@ifnottex +@math{c*b^n + a-i = 3*q}, +@end ifnottex +where @math{b} is the size of a limb +@tex +($2^{32}$ or $2^{64}$). +@end tex +@ifnottex +(@math{2^32} or @math{2^64}). +@end ifnottex +@math{c} is always 0, 1 or 2, and the initial carry must also be 0, 1 or 2 +(these are both borrows really). When @math{c=0}, clearly @math{q=(a-i)/3}. +When +@tex +$c \neq 0$, +the remainder $(a-i) \, mod \, 3$ +@end tex +@ifnottex +@math{c!=0}, the remainder @math{(a-i) mod 3} +@end ifnottex +is given by @math{3-c}, because +@tex +$b \equiv 1 \, mod \, 3$. +@end tex +@ifnottex +@math{b @equiv{} 1 mod 3}. +@end ifnottex +@end deftypefn + +@deftypefun mp_limb_t mpn_mod_1 (mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, mp_limb_t @var{s2limb}) Divide @{@var{s1p}, @var{s1size}@} by @var{s2limb}, and return the remainder. +@var{s1size} can be zero. @end deftypefun -@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}) +@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}) @strong{This interface is obsolete. It will disappear from future releases. Use @code{mpn_mod_1} in its stead.} @end deftypefun -@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}) +@deftypefun mp_limb_t mpn_bdivmod (mp_limb_t *@var{rp}, 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}) The function puts the low [@var{d}/@var{BITS_PER_MP_LIMB}] limbs of @var{q} = @{@var{s1p}, @var{s1size}@}/@{@var{s2p}, @var{s2size}@} mod 2^@var{d} -at @var{dest_ptr}, +at @var{rp}, and returns the high @var{d} mod @var{BITS_PER_MP_LIMB} bits of @var{q}. @{@var{s1p}, @var{s1size}@} - @var{q} * @{@var{s2p}, @var{s2size}@} @@ -2268,7 +3305,7 @@ is placed at @var{s1p}. Since the low [@var{d}/@var{BITS_PER_MP_LIMB}] limbs of this difference are zero, it is possible to overwrite the low limbs at @var{s1p} with this difference, -provided @var{dest_ptr} <= @var{s1p}. +provided @var{rp} <= @var{s1p}. This function requires that @var{s1size} * @var{BITS_PER_MP_LIMB} >= @var{D}, and that @{@var{s2p}, @var{s2size}@} is odd. @@ -2277,92 +3314,86 @@ and that @{@var{s2p}, @var{s2size}@} is odd. future revisions.} @end deftypefun -@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}) +@deftypefun mp_limb_t mpn_lshift (mp_limb_t *@var{rp}, const mp_limb_t *@var{src_ptr}, mp_size_t @var{src_size}, unsigned long int @var{count}) Shift @{@var{src_ptr}, @var{src_size}@} @var{count} bits to the left, and write the @var{src_size} least significant limbs of the result to -@var{dest_ptr}. @var{count} might be in the range 1 to n @minus{} 1, on an +@var{rp}. @var{count} might be in the range 1 to n @minus{} 1, on an n-bit machine. The bits shifted out to the left are returned. Overlapping of the destination space and the source space is allowed in this -function, provided @var{dest_ptr} >= @var{src_ptr}. +function, provided @var{rp} >= @var{src_ptr}. This function is written in assembly for most targets. @end deftypefun -@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}) +@deftypefun mp_limp_t mpn_rshift (mp_limb_t *@var{rp}, const mp_limb_t *@var{src_ptr}, mp_size_t @var{src_size}, unsigned long int @var{count}) Shift @{@var{src_ptr}, @var{src_size}@} @var{count} bits to the right, and write the @var{src_size} most significant limbs of the result to -@var{dest_ptr}. @var{count} might be in the range 1 to n @minus{} 1, on an +@var{rp}. @var{count} might be in the range 1 to n @minus{} 1, on an n-bit machine. The bits shifted out to the right are returned. Overlapping of the destination space and the source space is allowed in this -function, provided @var{dest_ptr} <= @var{src_ptr}. +function, provided @var{rp} <= @var{src_ptr}. This function is written in assembly for most targets. @end deftypefun -@deftypefun int mpn_cmp (const mp_limb_t * @var{src1_ptr}, const mp_limb_t * @var{src2_ptr}, mp_size_t @var{size}) -Compare @{@var{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@} and -return a positive value if src1 > src2, 0 of they are equal, and a negative -value if src1 < src2. +@deftypefun int mpn_cmp (const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{size}) +Compare @{@var{s1p}, @var{size}@} and @{@var{s2p}, @var{size}@} and +return a positive value if s1 > src2, 0 of they are equal, and a negative +value if s1 < src2. @end deftypefun -@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}) -Puts at @var{dest_ptr} the greatest common divisor of @{@var{src1_ptr}, -@var{src1_size}@} and @{@var{src2_ptr}, @var{src2_size}@}; both source +@deftypefun mp_size_t mpn_gcd (mp_limb_t *@var{rp}, mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, mp_limb_t *@var{s2p}, mp_size_t @var{s2size}) +Puts at @var{rp} the greatest common divisor of @{@var{s1p}, +@var{s1size}@} and @{@var{s2p}, @var{s2size}@}; both source operands are destroyed by the operation. The size in limbs of the greatest common divisor is returned. -@{@var{src1_ptr}, @var{src1_size}@} must be odd, and @{@var{src2_ptr}, -@var{src2_size}@} must have at least as many bits as @{@var{src1_ptr}, -@var{src1_size}@}. - -@strong{This interface is preliminary. It might change incompatibly in -future revisions.} +@{@var{s1p}, @var{s1size}@} must have at least as many bits as +@{@var{s2p}, @var{s2size}@}, and @{@var{s2p}, @var{s2size}@} must be odd. @end deftypefun -@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}) -Return the greatest common divisor of @{@var{src1_ptr}, @var{src1_size}@} -and @var{src2_limb}, where @var{src2_limb} (as well as @var{src1_size}) +@deftypefun mp_limb_t mpn_gcd_1 (const mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, mp_limb_t @var{s2limb}) +Return the greatest common divisor of @{@var{s1p}, @var{s1size}@} +and @var{s2limb}, where @var{s2limb} (as well as @var{s1size}) must be different from 0. @end deftypefun -@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}) -Puts at @var{r1p} the greatest common divisor of @{@var{s1p}, @var{s1size}@} -and @{@var{s2p}, @var{s2size}@}. The first cofactor is written at -@var{r2p}. Both source operands are destroyed by the operation. The size -in limbs of the greatest common divisor is returned. +@deftypefun mp_size_t mpn_gcdext (mp_limb_t *@var{r1p}, mp_limb_t *@var{r2p}, mp_size_t *@var{r2size}, mp_limb_t *@var{s1p}, mp_size_t @var{s1size}, mp_limb_t *@var{s2p}, mp_size_t @var{s2size}) +Compute the greatest common divisor of @{@var{s1p}, @var{s1size}@} and +@{@var{s2p}, @var{s2size}@}. Store the gcd at @var{r1p} and return its size +in limbs. Write the first cofactor at @var{r2p} and store its size in +*@var{r2size}. If the cofactor is negative, *@var{r2size} is negative and +@var{r2p} is the absolute value of the cofactor. -@strong{This interface is preliminary. It might change incompatibly in -future revisions.} +@{@var{s1p}, @var{s1size}@} must be greater than or equal to @{@var{s2p}, +@var{s2size}@}. Neither operand may equal 0. Both source operands are +destroyed, plus one limb past the end of each, ie. @{@var{s1p}, +@var{s1size}+1@} and @{@var{s2p}, @var{s2size}+1@}. @end deftypefun -@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}) +@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}) Compute the square root of @{@var{sp}, @var{size}@} and put the result at -@var{r1p}. Write the remainder at @var{r2p}, unless @var{r2p} is NULL. +@var{r1p}. Write the remainder at @var{r2p}, unless @var{r2p} is @code{NULL}. -Return the size of the remainder, whether @var{r2p} was NULL or non-NULL. +Return the size of the remainder, whether @var{r2p} was @code{NULL} or non-@code{NULL}. Iff the operand was a perfect square, the return value will be 0. The areas at @var{r1p} and @var{sp} have to be distinct. The areas at @var{r2p} and @var{sp} have to be identical or completely separate, not partially overlapping. -@ifinfo +@ifnottex The area at @var{r1p} needs to have space for ceil(@var{size}/2) limbs. -@end ifinfo -@iftex +@end ifnottex @tex The area at @var{r1p} needs to have space for $\lceil@var{size}/2\rceil$ limbs. @end tex -@end iftex The area at @var{r2p} needs to be @var{size} limbs large. - -@strong{This interface is preliminary. It might change incompatibly in -future revisions.} @end deftypefun -@deftypefun mp_size_t mpn_get_str (unsigned char *@var{str}, int @var{base}, mp_limb_t * @var{s1p}, mp_size_t @var{s1size}) +@deftypefun mp_size_t mpn_get_str (unsigned char *@var{str}, int @var{base}, mp_limb_t *@var{s1p}, mp_size_t @var{s1size}) Convert @{@var{s1p}, @var{s1size}@} to a raw unsigned char array in base @var{base}. The string is not in ASCII; to convert it to printable format, add the ASCII codes for @samp{0} or @samp{A}, depending on the base and @@ -2376,7 +3407,7 @@ The area at @var{str} has to have space for the larges represented by a @var{s1size} long limb array, plus one extra character. @end deftypefun -@deftypefun mp_size_t mpn_set_str (mp_limb_t * @var{r1p}, const char *@var{str}, size_t {strsize}, int @var{base}) +@deftypefun mp_size_t mpn_set_str (mp_limb_t *@var{r1p}, const char *@var{str}, size_t @var{strsize}, int @var{base}) Convert the raw unsigned char array at @var{str} of length @var{strsize} to a limb array @{@var{s1p}, @var{s1size}@}. The base of @var{str} is @var{base}. @@ -2384,55 +3415,210 @@ a limb array @{@var{s1p}, @var{s1size}@}. The base of Return the number of limbs stored in @var{r1p}. @end deftypefun -@deftypefun {unsigned long int} mpn_scan0 (const mp_limb_t * @var{s1p}, unsigned long int @var{bit}) +@deftypefun {unsigned long int} mpn_scan0 (const mp_limb_t *@var{s1p}, unsigned long int @var{bit}) Scan @var{s1p} from bit position @var{bit} for the next clear bit. It is required that there be a clear bit within the area at @var{s1p} at or beyond bit position @var{bit}, so that the function has something to return. - -@strong{This interface is preliminary. It might change incompatibly in -future revisions.} @end deftypefun -@deftypefun {unsigned long int} mpn_scan1 (const mp_limb_t * @var{s1p}, unsigned long int @var{bit}) +@deftypefun {unsigned long int} mpn_scan1 (const mp_limb_t *@var{s1p}, unsigned long int @var{bit}) Scan @var{s1p} from bit position @var{bit} for the next set bit. It is required that there be a set bit within the area at @var{s1p} at or beyond bit position @var{bit}, so that the function has something to return. - -@strong{This interface is preliminary. It might change incompatibly in -future revisions.} @end deftypefun -@deftypefun void mpn_random2 (mp_limb_t * @var{r1p}, mp_size_t @var{r1size}) -Generate a random number of length @var{r1size} with long strings of zeros -and ones in the binary representation, and store it at @var{r1p}. +@deftypefun void mpn_random (mp_limb_t *@var{r1p}, mp_size_t @var{r1size}) +@deftypefunx void mpn_random2 (mp_limb_t *@var{r1p}, mp_size_t @var{r1size}) +Generate a random number of length @var{r1size} and store it at @var{r1p}. +The most significant limb is always non-zero. @code{mpn_random} generates +uniformly distributed limb data, @code{mpn_random2} generates long strings of +zeros and ones in the binary representation. -The generated random numbers are intended for testing the correctness of the -implementation of the @code{mpn} routines. +@code{mpn_random2} is intended for testing the correctness of the @code{mpn} +routines. @end deftypefun -@deftypefun {unsigned long int} mpn_popcount (const mp_limb_t * @var{s1p}, unsigned long int @var{size}) +@deftypefun {unsigned long int} mpn_popcount (const mp_limb_t *@var{s1p}, unsigned long int @var{size}) Count the number of set bits in @{@var{s1p}, @var{size}@}. @end deftypefun -@deftypefun {unsigned long int} mpn_hamdist (const mp_limb_t * @var{s1p}, const mp_limb_t * @var{s2p}, unsigned long int @var{size}) +@deftypefun {unsigned long int} mpn_hamdist (const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, unsigned long int @var{size}) Compute the hamming distance between @{@var{s1p}, @var{size}@} and @{@var{s2p}, @var{size}@}. @end deftypefun -@deftypefun int mpn_perfect_square_p (const mp_limb_t * @var{s1p}, mp_size_t @var{size}) +@deftypefun int mpn_perfect_square_p (const mp_limb_t *@var{s1p}, mp_size_t @var{size}) Return non-zero iff @{@var{s1p}, @var{size}@} is a perfect square. @end deftypefun -@node BSD Compatible Functions, Custom Allocation, Low-level Functions, Top +@node Random Number Functions, BSD Compatible Functions, Low-level Functions, Top +@chapter Random Number Functions +@cindex Random number functions + +There are two groups of random number functions in GNU MP; older +functions that call C library random number generators, rely on a global +state, and aren't very random; and newer functions that don't have these +problems. The newer functions are self-contained, they accept a random +state parameter that supplants global state, and generate good random +numbers. + +The random state parameter is of the type @code{gmp_randstate_t}. It must be +initialized by a call to one of the @code{gmp_randinit} functions (@ref{Random +State Initialization}). The initial seed is set using one of the +@code{gmp_randseed} functions (@ref{Random State Initialization}). + +The size of the seed determines the number of different sequences of +random numbers that is possible to generate. The ``quality'' of the +seed is the randomness of a given seed compared to the previous seed +used and affects the randomness of separate number sequences. + +The algorithm for assigning seed is critical if the generated random numbers +are to be used for important applications, such as generating cryptographic +keys. + +The traditional method is to use the current system time for seeding. One has +to be careful when using the current time though. If the application seeds the +random functions very often, say several times per second, and the resolution +of the system clock is comparatively low, like one second, the same sequence of +numbers will be generated until the system clock ticks. Furthermore, the +current system time is quite easy to guess, so a system depending on any +unpredictability of the random number sequence should absolutely not use that +as its only source for a seed value. + +On some systems there is a special device, often called @code{/dev/random}, +which provides a source of somewhat random numbers more usable as seed. + +The functions actually generating random functions are documented under +``Miscellaneous Functions'' in their respective function class: +@ref{Miscellaneous Integer Functions}, @ref{Miscellaneous Float Functions}. + +@menu +* Random State Initialization:: How to initialize a random state. +@end menu + +@node Random State Initialization, , Random Number Functions, Random Number Functions +@section Random State Initialization +@cindex Random number state + +See @ref{Random Number Functions} for a discussion on how to choose the +initial seed value passed to these functions. + +@deftypefun void gmp_randinit (gmp_randstate_t @var{state}, gmp_randalg_t @var{alg}, ...) +Initialize random state variable @var{state}. + +@var{alg} denotes what algorithm to use for random number generation. +Use one of +@itemize @minus +@item GMP_RAND_ALG_LC --- Linear congruential. + +A fast generator defined by @math{X = (aX + c) mod m}. + +A third argument @var{size} of type unsigned long int is required. @var{size} +is the size of the largest good quality random number to be generated, +expressed in number of bits. If the random generation functions are asked for +a bigger random number than indicated by this parameter, two or more numbers +of @var{size} bits will be generated and concatenated, resulting in a ``bad'' +random number. This can be used to generate big random numbers relatively +cheap if the quality of randomness isn't of great importance. + +a, c, and m are picked from a table where the modulus (m) is a power of 2 and +the multiplier is congruent to 5 (mod 8). The choice is based on the +@var{size} parameter. The maximum @var{size} supported by this algorithm is +128. If you need bigger random numbers, use your own scheme and call one of +the other @code{gmp_randinit} functions. + +@ignore +@item GMP_RAND_ALG_BBS --- Blum, Blum, and Shub. +@end ignore +@end itemize + +If @var{alg} is 0 or GMP_RAND_ALG_DEFAULT, the default algorithm is used. The +default algorithm is typically a fast algorithm like the linear congruential +and requires a third @var{size} argument (see GMP_RAND_ALG_LC). + +When you're done with a @var{state} variable, call @code{gmp_randclear} +to deallocate any memory allocated by this function. + +@code{gmp_randinit} may set the following bits in @var{gmp_errno}: +@c FIXME: gmp_errno is printed in uppercase. That's wrong. +@itemize +@item GMP_ERROR_UNSUPPORTED_ARGUMENT --- @var{alg} is unsupported +@item GMP_ERROR_INVALID_ARGUMENT --- @var{size} is too big +@end itemize +@end deftypefun + + +@ignore +@deftypefun void gmp_randinit_lc (gmp_randstate_t @var{state}, mpz_t @var{a}, +unsigned long int @var{c}, mpz_t @var{m}) + +Initialize random state variable @var{state} with given linear congruential +scheme. + +Parameters @var{a}, @var{c}, and @var{m} are the multiplier, adder, and modulus +for the linear congruential scheme to use, respectively. + +When you're done with a @var{state} variable, call @code{gmp_randclear} +to deallocate any memory allocated by this function. +@end deftypefun +@end ignore + +@deftypefun void gmp_randinit_lc_2exp (gmp_randstate_t @var{state}, mpz_t @var{a}, +unsigned long int @var{c}, unsigned long int @var{m2exp}) + +Initialize random state variable @var{state} with given linear congruential +scheme. + +Parameters @var{a}, @var{c}, and @var{m2exp} are the multiplier, adder, and +modulus for the linear congruential scheme to use, respectively. The modulus +is expressed as a power of 2, so that +@ifnottex +@var{m} = 2^@var{m2exp}. +@end ifnottex +@tex +$m = 2^{m2exp}$. +@end tex + +The least significant bits of a random number generated by the linear +congruential algorithm where the modulus is a power of two are not very random. +Therefore, the lower half of a random number generated by an LC scheme +initialized with this function is discarded. Thus, the size of a random number +is @var{m2exp} / 2 (rounded upwards) bits when this function has been used for +initializing the random state. + +When you're done with a @var{state} variable, call @code{gmp_randclear} +to deallocate any memory allocated by this function. +@end deftypefun + +@deftypefun void gmp_randseed (gmp_randstate_t @var{state}, mpz_t @var{seed}) +@deftypefunx void gmp_randseed_ui (gmp_randstate_t @var{state}, unsigned long int @var{seed}) + +Set the initial seed value. + +Parameter @var{seed} is the initial random seed. The function +@code{gmp_randseed_ui} takes the @var{seed} as an unsigned long int rather +than as an mpz_t. +@end deftypefun + +@deftypefun void gmp_randclear (gmp_randstate_t @var{state}) +Free all memory occupied by @var{state}. Make sure to call this +function for all @code{gmp_randstate_t} variables when you are done with +them. +@end deftypefun + +@node BSD Compatible Functions, Custom Allocation, Random Number Functions, Top @comment node-name, next, previous, up @chapter Berkeley MP Compatible Functions +@cindex Berkeley MP compatible functions @cindex BSD MP compatible functions These functions are intended to be fully compatible with the Berkeley MP -library which is available on many BSD derived U*ix systems. +library which is available on many BSD derived U*ix systems. The +@samp{--enable-mpbsd} option must be used when building GNU MP to make these +available (@pxref{Installing GMP}). The original Berkeley MP library has a usage restriction: you cannot use the same variable as both source and destination in a single function call. The @@ -2447,7 +3633,7 @@ with @code{pow} in @file{libm.a}. @cindex @file{mp.h} Include the header @file{mp.h} to get the definition of the necessary types and functions. If you are on a BSD derived system, make sure to include GNU -@file{mp.h} if you are going to link the GNU @file{libmp.a} to you program. +@file{mp.h} if you are going to link the GNU @file{libmp.a} to your program. This means that you probably need to give the -I option to the compiler, where is the directory where you have GNU @file{mp.h}. @@ -2493,17 +3679,15 @@ negative arguments. @end deftypefun @deftypefun void msqrt (MINT *@var{operand}, MINT *@var{root}, MINT *@var{remainder}) -@ifinfo +@ifnottex Set @var{root} to the truncated integer part of the square root of @var{operand}. Set @var{remainder} to @var{operand}@minus{}@var{root}*@var{root}, -@end ifinfo -@iftex +@end ifnottex @tex Set @var{root} to $\lfloor\sqrt{@var{operand}}\rfloor$, like @code{mpz_sqrt}. Set @var{remainder} to $(operand - root^2)$, @end tex -@end iftex (i.e., zero if @var{operand} is a perfect square). If @var{root} and @var{remainder} are the same variable, the results are @@ -2549,27 +3733,32 @@ De-allocate, the space used by @var{operand}. @strong only be passed a value returned by @code{itom} or @code{xtom}.} @end deftypefun + @node Custom Allocation, Contributors, BSD Compatible Functions, Top @comment node-name, next, previous, up @chapter Custom Allocation +@cindex Custom allocation +@cindex Memory allocation +@cindex Allocation of memory -By default, the MP functions use @code{malloc}, @code{realloc}, and -@code{free} for memory allocation. If @code{malloc} or @code{realloc} fails, -the MP library terminates execution after printing a fatal error message to -standard error. +By default, GMP uses @code{malloc}, @code{realloc} and @code{free} for memory +allocation. If @code{malloc} or @code{realloc} fails, GMP prints a message to +the standard error output and terminates execution. -For some applications, you may wish to allocate memory in other ways, or you -may not want to have a fatal error when there is no more memory available. To -accomplish this, you can specify alternative memory allocation functions. +Some applications might want to allocate memory in other ways, or might not +want a fatal error when there is no more memory available. To accomplish +this, you can specify alternative memory allocation functions. +This can be done in the Berkeley compatibility library as well as the main GMP +library. + @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)) Replace the current allocation functions from the arguments. If an argument -is NULL, the corresponding default function is retained. +is @code{NULL}, the corresponding default function is retained. -@strong{Make sure to call this function in such a way that there are no active -MP objects that were allocated using the previously active allocation -function! Usually, that means that you have to call this function before any -other MP function.} +@strong{Be sure to call this function only when there are no active GMP +objects allocated using the previous memory functions! Usually, that means +that you have to call this function before any other GMP function.} @end deftypefun The functions you supply should fit the following declarations: @@ -2605,12 +3794,21 @@ the size of an object, normally an 8 bit byte.) @node Contributors, References, Custom Allocation, Top @comment node-name, next, previous, up @unnumbered Contributors +@cindex Contributors -I would like to thank Gunnar Sjoedin and Hans Riesel for their help with -mathematical problems, Richard Stallman for his help with design issues and -for revising the first version of this manual, Brian Beuning and Doug Lea for -their testing of early versions of the library. +Torbjorn Granlund wrote the original GMP library and is still developing and +maintaining it. Several other individuals and organizations have contributed +to GMP in various ways. Here is a list in chronological order: +Gunnar Sjoedin and Hans Riesel helped with mathematical problems in early +versions of the library. + +Richard Stallman contributed to the interface design and revised the first +version of this manual. + +Brian Beuning and Doug Lea helped with testing of early versions of the +library and made creative suggestions. + John Amanatides of York University in Canada contributed the function @code{mpz_probab_prime_p}. @@ -2621,45 +3819,79 @@ Ken Weber (Kent State University, Universidade Federal contributed @code{mpz_gcd}, @code{mpz_divexact}, @code{mpn_gcd}, and @code{mpn_bdivmod}, partially supported by CNPq (Brazil) grant 301314194-2. -Per Bothner of Cygnus Support helped to set up MP to use Cygnus' configure. +Per Bothner of Cygnus Support helped to set up GMP to use Cygnus' configure. He has also made valuable suggestions and tested numerous intermediary releases. Joachim Hollman was involved in the design of the @code{mpf} interface, and in the @code{mpz} design revisions for version 2. -Bennet Yee contributed the functions @code{mpz_jacobi} and -@code{mpz_legendre}. +Bennet Yee contributed the functions @code{mpz_jacobi} and @code{mpz_legendre}. Andreas Schwab contributed the files @file{mpn/m68k/lshift.S} and @file{mpn/m68k/rshift.S}. -The development of floating point functions of GNU MP 2, were supported in -part by the ESPRIT-BRA (Basic Research Activities) 6846 project POSSO -(POlynomial System SOlving). +The development of floating point functions of GNU MP 2, were supported in part +by the ESPRIT-BRA (Basic Research Activities) 6846 project POSSO (POlynomial +System SOlving). -GNU MP 2 was finished and released by TMG Datakonsult, Sodermannagatan 5, 116 -23 STOCKHOLM, SWEDEN, in cooperation with the IDA Center for Computing -Sciences, USA. +GNU MP 2 was finished and released by SWOX AB (formerly known as TMG +Datakonsult), Swedenborgsgatan 23, SE-118 27 STOCKHOLM, SWEDEN, in +cooperation with the IDA Center for Computing Sciences, USA. +Robert Harley of Inria, France and David Seal of ARM, England, suggested clever +improvements for population count. -@node References, , Contributors, Top +Robert Harley also wrote highly optimized Karatsuba and 3-way Toom +multiplication functions for GMP 3. He also contributed the ARM assembly +code. + +Torsten Ekedahl of the Mathematical department of Stockholm University provided +significant inspiration during several phases of the GMP development. His +mathematical expertise helped improve several algorithms. + +Paul Zimmermann wrote the Burnikel-Ziegler division code, the REDC code, the +REDC-based mpz_powm code, and the FFT multiply code. The ECMNET project Paul +is organizing has been a driving force behind many of the optimization of GMP +3. + +Linus Nordberg wrote the new configure system based on autoconf and +implemented the new random functions. + +Kent Boortz made the Macintosh port. + +Kevin Ryde wrote a lot of very high quality x86 code, optimized for most CPU +variants. He also made countless other valuable contributions. + +Steve Root helped write the optimized alpha 21264 assembly code. + +GNU MP 3.1 was finished and released by Torbjorn Granlund and Kevin Ryde. +Torbjorn's work was partially funded by the IDA Center for Computing Sciences, +USA. + +(This list is chronological, not ordered after significance. If you have +contributed to GMP but are not listed above, please tell @email{tege@@swox.com} +about the omission!) + +@node References, Concept Index, Contributors, Top @comment node-name, next, previous, up @unnumbered References +@cindex References @itemize @bullet @item Donald E. Knuth, "The Art of Computer Programming", vol 2, -"Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981. +"Seminumerical Algorithms", 3rd edition, Addison-Wesley, 1988. @item John D. Lipson, "Elements of Algebra and Algebraic Computing", The Benjamin Cummings Publishing Company Inc, 1981. @item -Richard M. Stallman, "Using and Porting GCC", Free Software Foundation, -1995. +Richard M. Stallman, "Using and Porting GCC", Free Software Foundation, 1999, +available online @uref{http://www.gnu.org/software/gcc/onlinedocs/}, and in +the GCC package @uref{ftp://ftp.gnu.org/pub/gnu/gcc/}. @item Peter L. Montgomery, "Modular Multiplication Without Trial Division", in @@ -2668,26 +3900,43 @@ Mathematics of Computation, volume 44, number 170, Apr @item Torbjorn Granlund and Peter L. Montgomery, "Division by Invariant Integers using Multiplication", in Proceedings of the SIGPLAN -PLDI'94 Conference, June 1994. +PLDI'94 Conference, June 1994. Available online, @* +@uref{ftp://ftp.cwi.nl/pub/pmontgom/divcnst.psa4.gz} (and .psl.gz too). @item Tudor Jebelean, "An algorithm for exact division", Journal of Symbolic Computation, v. 15, 1993, pp. 169-180. +Research report version available online @* +@uref{ftp://ftp.risc.uni-linz.ac.at/pub/techreports/1992/92-35.ps.gz} @item Kenneth Weber, "The accelerated integer GCD algorithm", ACM Transactions on Mathematical Software, v. 21 (March), 1995, pp. 111-122. + +@item +Christoph Burnikel and Joachim Ziegler, "Fast Recursive Division", +Max-Planck-Institut fuer Informatik Research Report MPI-I-98-1-022, @* +@uref{http://www.mpi-sb.mpg.de/~ziegler/TechRep.ps.gz}. + +@item +Alfred J. Menezes, Paul C. van Oorschot and Scott A. Vanstone, "Handbook of +Applied Cryptography", @uref{http://cacr.math.uwaterloo.ca/hac/}. + +@item +Henri Cohen, "A Course in Computational Algebraic Number Theory", Graduate +Texts in Mathematics number 138, Springer-Verlag, 1993. Errata available +online @* @uref{http://www.math.u-bordeaux.fr/~cohen} @end itemize -@node Concept Index, , , Top +@node Concept Index, Function Index, References, Top @comment node-name, next, previous, up @unnumbered Concept Index @printindex cp -@node Function Index, , , Top +@node Function Index, , Concept Index, Top @comment node-name, next, previous, up @unnumbered Function and Type Index @printindex fn @@ -2695,3 +3944,7 @@ v. 21 (March), 1995, pp. 111-122. @contents @bye + +@c Local variables: +@c fill-column: 78 +@c End: