version 1.1, 2000/01/10 15:35:21 |
version 1.1.1.2, 2000/09/09 14:12:16 |
|
|
\input texinfo @c -*-texinfo-*- |
\input texinfo @c -*-texinfo-*- |
@c %**start of header |
@c %**start of header |
@setfilename gmp.info |
@setfilename gmp.info |
@settitle GNU MP 2.0.2 |
@include version.texi |
|
@settitle GNU MP @value{VERSION} |
@synindex tp fn |
@synindex tp fn |
@iftex |
@iftex |
@afourpaper |
@afourpaper |
@end iftex |
@end iftex |
@comment %**end of header |
@comment %**end of header |
|
|
@ifinfo |
@dircategory GNU libraries |
@format |
@direntry |
START-INFO-DIR-ENTRY |
* gmp: (gmp). GNU Multiple Precision Arithmetic Library. |
* gmp: (gmp.info). GNU Multiple Precision Arithmetic Library. |
@end direntry |
END-INFO-DIR-ENTRY |
|
@end format |
|
@end ifinfo |
|
|
|
@c smallbook |
@c smallbook |
|
|
Line 22 END-INFO-DIR-ENTRY |
|
Line 20 END-INFO-DIR-ENTRY |
|
@finalout |
@finalout |
@end iftex |
@end iftex |
|
|
@c Note: the edition number is listed in *three* places; please update |
@c Texinfo version 4 or up will be needed to process this into .info files. |
@c all three. Also, update the month and year where appropriate. |
@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. |
|
|
|
|
@ifnottex |
@ifinfo |
|
This file documents GNU MP, a library for arbitrary-precision arithmetic. |
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 |
Permission is granted to make and distribute verbatim copies of |
this manual provided the copyright notice and this permission notice |
this manual provided the copyright notice and this permission notice |
Line 43 Permission is granted to process this file through TeX |
|
Line 43 Permission is granted to process this file through TeX |
|
results, provided the printed document carries copying permission |
results, provided the printed document carries copying permission |
notice identical to this one except for the removal of this paragraph |
notice identical to this one except for the removal of this paragraph |
(this paragraph not being relevant to the printed manual). |
(this paragraph not being relevant to the printed manual). |
|
|
@end ignore |
@end ignore |
|
|
Permission is granted to copy and distribute modified versions of this |
Permission is granted to copy and distribute modified versions of this |
manual under the conditions for verbatim copying, provided that the entire |
manual under the conditions for verbatim copying, provided that the entire |
resulting derived work is distributed under the terms of a permission |
resulting derived work is distributed under the terms of a permission |
Line 54 Permission is granted to copy and distribute translati |
|
Line 54 Permission is granted to copy and distribute translati |
|
into another language, under the above conditions for modified versions, |
into another language, under the above conditions for modified versions, |
except that this permission notice may be stated in a translation approved |
except that this permission notice may be stated in a translation approved |
by the Foundation. |
by the Foundation. |
@end ifinfo |
@end ifnottex |
|
|
@setchapternewpage on |
@setchapternewpage on |
@titlepage |
@titlepage |
Line 62 by the Foundation. |
|
Line 62 by the Foundation. |
|
|
|
@title GNU MP |
@title GNU MP |
@subtitle The GNU Multiple Precision Arithmetic Library |
@subtitle The GNU Multiple Precision Arithmetic Library |
@subtitle Edition 2.0.2 |
@subtitle Edition @value{EDITION} |
@subtitle June 1996 |
@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 Include the Distribution inside the titlepage so |
@c that headings are turned off. |
@c that headings are turned off. |
Line 78 by the Foundation. |
|
Line 79 by the Foundation. |
|
|
|
@page |
@page |
@vskip 0pt plus 1filll |
@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 |
@sp 2 |
|
|
Line 102 by the Foundation. |
|
Line 104 by the Foundation. |
|
@end titlepage |
@end titlepage |
@headings double |
@headings double |
|
|
@ifinfo |
@ifnottex |
@node Top, Copying, (dir), (dir) |
@node Top, Copying, (dir), (dir) |
|
|
@top GNU MP |
@top GNU MP |
|
|
This manual documents how to install and use the GNU multiple precision |
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 |
@menu |
* Copying:: GMP Copying Conditions (LGPL). |
* Copying:: GMP Copying Conditions (LGPL). |
* Introduction to MP:: Brief introduction to GNU MP. |
* Introduction to GMP:: Brief introduction to GNU MP. |
* Installing MP:: How to configure and compile the MP library. |
* Installing GMP:: How to configure and compile the GMP library. |
* MP Basics:: What every MP user should now. |
* GMP Basics:: What every GMP user should now. |
* Reporting Bugs:: How to usefully report bugs. |
* Reporting Bugs:: How to usefully report bugs. |
* Integer Functions:: Functions for arithmetic on signed integers. |
* Integer Functions:: Functions for arithmetic on signed integers. |
* Rational Number Functions:: Functions for arithmetic on rational numbers. |
* Rational Number Functions:: Functions for arithmetic on rational numbers. |
* Floating-point Functions:: Functions for arithmetic on floats. |
* Floating-point Functions:: Functions for arithmetic on floats. |
* Low-level Functions:: Fast functions for natural numbers. |
* Low-level Functions:: Fast functions for natural numbers. |
* BSD Compatible Functions:: All functions found in BSD MP. |
* Random Number Functions:: Functions for generating random numbers. |
* Custom Allocation:: How to customize the internal allocation. |
* BSD Compatible Functions:: All functions found in BSD MP. |
|
* Custom Allocation:: How to customize the internal allocation. |
|
|
* Contributors:: |
* Contributors:: Who brings your this library? |
* References:: |
* References:: Some useful papers and books to read. |
* Concept Index:: |
* Concept Index:: |
* Function Index:: |
* Function Index:: |
@end menu |
@end menu |
|
|
@node Copying, Introduction to MP, Top, Top |
@node Copying, Introduction to GMP, Top, Top |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
@unnumbered GNU MP Copying Conditions |
@unnumbered GNU MP Copying Conditions |
@cindex Copying conditions |
@cindex Copying conditions |
Line 165 will not reflect on our reputation.@refill |
|
Line 168 will not reflect on our reputation.@refill |
|
The precise conditions of the license for the GNU MP library are found in the |
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 |
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 |
@comment node-name, next, previous, up |
@chapter Introduction to GNU MP |
@chapter Introduction to GNU MP |
|
@cindex Introduction |
|
|
|
|
GNU MP is a portable library written in C for arbitrary precision arithmetic |
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 |
on integers, rational numbers, and floating-point numbers. It aims to provide |
the fastest possible arithmetic for all applications that need higher |
the fastest possible arithmetic for all applications that need higher |
precision than is directly supported by the basic C types. |
precision than is directly supported by the basic C types. |
|
|
Many applications use just a few hundred bits of precision; but some |
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 |
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 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 |
by using sophisticated algorithms, by including carefully optimized assembly |
code for the most common inner loops for many different CPUs, and by a general |
code for the most common inner loops for many different CPUs, and by a general |
emphasis on speed (as opposed to simplicity or elegance). |
emphasis on speed (as opposed to simplicity or elegance). |
|
|
There is carefully optimized assembly code for these CPUs: DEC Alpha, Amd |
There is carefully optimized assembly code for these CPUs: |
29000, HPPA 1.0 and 1.1, Intel Pentium and generic x86, Intel i960, Motorola |
@cindex CPUs supported |
MC68000, MC68020, MC88100, and MC88110, Motorola/IBM PowerPC, National |
ARM, |
NS32000, IBM POWER, MIPS R3000, R4000, SPARCv7, SuperSPARC, generic SPARCv8, |
DEC Alpha 21064, 21164, and 21264, |
and DEC VAX. Some optimizations also for ARM, Clipper, IBM ROMP (RT), and |
AMD 29000, |
Pyramid AP/XP. |
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 |
@cindex Mailing list |
versions. It is now permitted to link MP to non-free programs, as long as MP |
There is a mailing list for GMP users. To join it, send a mail to |
source code is provided when distributing the non-free program. |
@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 |
@section How to use this Manual |
|
@cindex About this manual |
|
|
Everyone should read @ref{MP Basics}. If you need to install the library |
Everyone should read @ref{GMP Basics}. If you need to install the library |
yourself, you need to read @ref{Installing MP}, too. |
yourself, you need to read @ref{Installing GMP}, too. |
|
|
The rest of the manual can be used for later reference, although it is |
The rest of the manual can be used for later reference, although it is |
probably a good idea to glance through it. |
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 |
@comment node-name, next, previous, up |
@chapter Installing MP |
@chapter Installing GMP |
@cindex Installation |
@cindex Installing GMP |
|
@cindex Configuring GMP |
|
|
To build MP, you first have to configure it for your CPU and operating system. |
@noindent |
You need a C compiler, preferably GCC, but any reasonable compiler should |
GMP has an autoconf/automake/libtool based configuration system. On a |
work. And you need a standard Unix @samp{make} program, plus some other |
Unix-like system a basic build can be done with |
standard Unix utility programs. |
|
|
|
(If you're on an MS-DOS machine, your can build MP using @file{make.bat}. It |
@example |
requires that djgpp is installed. It does not require configuration, nor is |
./configure |
@samp{make} needed; @file{make.bat} both configures and builds the library.) |
make |
|
@end example |
|
|
Here are the steps needed to install the library on Unix systems: |
@noindent |
|
Some self-tests can be run with |
|
|
@enumerate |
@example |
@item |
make check |
In most cases, @samp{./configure --target=cpu-vendor-os}, should work both for |
@end example |
native and cross-compilation. If you get error messages, your machine might |
|
not be supported. |
|
|
|
If you want to compile in a separate object directory, cd to that directory, |
@noindent |
and prefix the configure command with the path to the MP source directory. |
And you can install (under @file{/usr/local} by default) with |
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. |
|
|
|
In addition to the standard cpu-vendor-os tuples, MP recognizes sparc8 and |
@example |
supersparc as valid CPU names. Specifying these CPU names for relevant |
make install |
systems will improve performance significantly. |
@end example |
|
|
In general, if you want a library that runs as fast as possible, you should |
@noindent |
make sure you configure MP for the exact CPU type your system uses. |
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 |
@menu |
override this, pass @samp{-with-gcc=no} to @file{configure}. |
* 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 |
@node Build Options, ABI and ISA, Installing GMP, Installing GMP |
working directory. |
@section Build Options |
|
@cindex Build options |
|
|
@item |
@noindent |
@samp{make check} |
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 |
@table @asis |
report this to @samp{bug-gmp@@prep.ai.mit.edu}. (@xref{Reporting Bugs}, for |
@item Non-Unix Systems |
information on what to include in useful bug reports.) |
|
|
|
@item |
@samp{configure} needs various Unix-like tools installed. On an MS-DOS system |
@samp{make install} |
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 |
@item Object Directory |
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 |
|
|
|
@noindent |
To compile in a separate object directory, @command{cd} to that directory, and |
If you wish to build and install the BSD MP compatible functions, use |
prefix the configure command with the path to the GMP source directory. For |
@samp{make libmp.a} and @samp{make install-bsdmp}. |
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 |
@itemize @bullet |
@item |
|
@samp{doc} |
|
|
|
Create a DVI version of the manual, in @file{gmp.dvi} and a set of info files, |
@c Keep this formatting, it's easy to read and it can be grepped to |
in @file{gmp.info}, @file{gmp.info-1}, @file{gmp.info-2}, etc. |
@c automatically test that targets listed get through ./config.sub |
|
|
@item |
@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 |
@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 |
@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 |
@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 |
@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 |
@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 |
The C compiler used is chosen from among some likely candidates, with GCC |
compile MP, due to a bug in GCC. If you want to use GCC for these machines, |
normally preferred if it's present. The usual @samp{CC=whatever} can be |
you need to apply the patch below to GCC, or use a later version of the |
passed to @samp{./configure} to choose something different. |
compiler. |
|
|
|
If you are on a Sequent Symmetry, use the GNU assembler instead of the |
For some configurations specific compiler flags are set based on the target |
system's assembler, since the latter has serious bugs. |
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 |
If @samp{CC} is set then @samp{CFLAGS} must also be set. This applies even if |
calls itself @file{cc}. This compiler cannot be used to build MP. You need |
@samp{CC} is merely one of the choices GMP would make itself. This may change |
to get a real gcc, and install that before you compile MP. (NeXT might have |
in a future release. |
fixed this in newer releases of their system.) |
|
|
|
The system C compiler under SunOS 4 has a bug that makes it miscompile |
@item @option{--disable-alloca} |
mpq/get_d.c. This will make @samp{make check} fail. |
@cindex Stack overflow segfaults |
|
@cindex @code{alloca} |
|
|
Please report other problems to @samp{bug-gmp@@prep.ai.mit.edu}. |
By default, GMP allocates temporary workspace using @code{alloca} if that |
@xref{Reporting Bugs}. |
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 |
@example |
*** config/rs6000/rs6000.md Sun Feb 11 08:22:11 1996 |
c89 +DA2.0 +e -D_LONG_LONG_LIMB |
--- 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 "" |
|
@end example |
@end example |
|
|
@node MP Basics, Reporting Bugs, Installing MP, Top |
A 32-bit limb is used in other cases, and no special compiler options are |
@comment node-name, next, previous, up |
needed. |
@chapter MP Basics |
|
|
|
|
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(<GSYM_PREFIX>, <_>)}. |
|
|
|
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} |
@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. |
@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 |
@section Nomenclature and Types |
|
@cindex Nomenclature |
|
@cindex Types |
|
|
@cindex Integer |
@cindex Integer |
@tindex @code{mpz_t} |
@tindex @code{mpz_t} |
@noindent |
@noindent |
In this manual, @dfn{integer} usually means a multiple precision integer, as |
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: |
Here are some examples of how to declare such integers: |
|
|
@example |
@example |
|
|
@tindex @code{mpf_t} |
@tindex @code{mpf_t} |
@noindent |
@noindent |
@dfn{Floating point number} or @dfn{Float} for short, is an arbitrary precision |
@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}. |
is @code{mpf_t}. |
|
|
@cindex Limb |
@cindex Limb |
Line 404 digit, only larger, and containing several digits.) N |
|
Line 827 digit, only larger, and containing several digits.) N |
|
32 or 64 bits. The C data type for a limb is @code{mp_limb_t}. |
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 |
@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 |
@enumerate |
@item |
@item |
Line 426 Functions for floating-point arithmetic, with names be |
|
Line 851 Functions for floating-point arithmetic, with names be |
|
functions is this class. |
functions is this class. |
|
|
@item |
@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}. |
@code{mult}. The associated type is @code{MINT}. |
|
|
@item |
@item |
Line 438 from very time-critical user programs. These function |
|
Line 863 from very time-critical user programs. These function |
|
The associated type is array of @code{mp_limb_t}. |
The associated type is array of @code{mp_limb_t}. |
|
|
@item |
@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 |
@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. |
arguments. This notation is based on an analogy with the assignment operator. |
(The BSD MP compatibility functions disobey this rule, having the output |
(The BSD MP compatibility functions disobey this rule, having the output |
argument(s) last.) |
argument(s) last.) |
|
|
MP allows you to use the same variable for both input and output in the same |
GMP lets you use the same variable for both input and output in one call. For |
expression. For example, the main function for integer multiplication, |
example, the main function for integer multiplication, @code{mpz_mul}, can be |
@code{mpz_mul}, can be used like this: @code{mpz_mul (x, x, x)}. This |
used to square @code{x} and put the result back in @code{x} with |
computes the square of @var{x} and puts the result back in @var{x}. |
|
|
|
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 |
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 |
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 |
purpose. Which function to use depends on the type of variable. See the |
Line 465 A variable should only be initialized once, or at leas |
|
Line 898 A variable should only be initialized once, or at leas |
|
each initialization. After a variable has been initialized, it may be |
each initialization. After a variable has been initialized, it may be |
assigned to any number of times. |
assigned to any number of times. |
|
|
For efficiency reasons, avoid to initialize and clear out a variable in loops. |
For efficiency reasons, avoid initializing and clearing out a GMP variable in |
Instead, initialize it before entering the loop, and clear it out after the |
a loop. Instead, initialize it before entering the loop, and clear it out |
loop has exited. |
after the loop has exited. |
|
|
You don't need to be concerned about allocating additional space for MP |
GMP variables are small, containing only a couple of sizes, and pointers to |
variables. All functions in MP automatically allocate additional space when a |
allocated data. Once you have initialized a GMP variable, you don't need to |
variable does not already have enough space. They do not, however, reduce the |
worry about space allocation. All functions in GMP automatically allocate |
space when a smaller number is stored in the object. Most of the time, this |
additional space when a variable does not already have enough. They do not, |
policy is best, since it avoids frequent re-allocation. |
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 |
@section Useful Macros and Constants |
|
@cindex Useful macros and constants |
|
@cindex Constants |
|
|
@deftypevr {Global Constant} {const int} mp_bits_per_limb |
@deftypevr {Global Constant} {const int} mp_bits_per_limb |
|
@cindex Bits per limb |
|
@cindex Limb size |
The number of bits per limb. |
The number of bits per limb. |
@end deftypevr |
@end deftypevr |
|
|
@defmac __GNU_MP_VERSION |
@defmac __GNU_MP_VERSION |
@defmacx __GNU_MP_VERSION_MINOR |
@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 |
@end defmac |
|
|
@section Compatibility with Version 1.x |
|
|
|
This version of MP is upward compatible with previous versions of MP, with a |
@node Compatibility with older versions, Getting the Latest Version of GMP, Useful Macros and Constants, GMP Basics |
few exceptions. |
@section Compatibility with older versions |
|
@cindex Compatibility with older versions |
|
@cindex Upward compatibility |
|
|
@enumerate |
This version of GMP is upwardly binary compatible with versions 3.0 and 3.0.1, |
@item Integer division functions round the result differently. The old |
and upwardly compatible at the source level with versions 2.0, 2.0.1, and |
functions (@code{mpz_div}, @code{mpz_divmod}, @code{mpz_mdiv}, |
2.0.2, with the following exceptions. |
@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. |
|
|
|
@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 |
@item |
@strong{mod} for reduction. |
@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 |
@end itemize |
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. |
|
|
|
@item Output generated by @code{mpz_out_raw} in this release cannot be read |
There are a number of compatibility issues between GMP 1 and GMP 2 that of |
by @code{mpz_inp_raw} in previous releases. This change was made for making |
course also apply when porting applications from GMP 1 to GMP 3. Please |
the file format truly portable between machines with different word sizes. |
see the GMP 2 manual for details. |
|
|
@item Several @code{mpn} functions have changed. But they were intentionally |
@c @enumerate |
undocumented in previous releases. |
@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} |
@c @item The function @code{mpz_mod} now compute the true @strong{mod} function. |
are now implementated as macros, and thereby sometimes evaluate their |
|
arguments multiple times. |
|
|
|
@item The functions @code{mpz_pow_ui} and @code{mpz_ui_pow_ui} now yield 1 |
@c @item The functions @code{mpz_powm} and @code{mpz_powm_ui} now use |
for 0^0. (In version 1, they yielded 0.) |
@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 |
@c @item The functions @code{mpz_cmp_ui}, @code{mpz_cmp_si}, and @code{mpq_cmp_ui} |
from @samp{prep.ai.mit.edu}. The file name is |
@c are now implemented as macros, and thereby sometimes evaluate their |
@file{/pub/gnu/gmp-M.N.tar.gz}. Many sites around the world mirror |
@c arguments multiple times. |
@samp{prep}; please use a mirror site near you. |
|
|
|
@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 |
@comment node-name, next, previous, up |
@chapter Reporting Bugs |
@chapter Reporting Bugs |
@cindex Reporting bugs |
@cindex Reporting bugs |
|
@cindex Bug reporting |
|
|
If you think you have found a bug in the MP library, please investigate it and |
If you think you have found a bug in the GMP library, please investigate it |
report it. We have made this library available to you, and it is not to ask |
and report it. We have made this library available to you, and it is not too |
too much from you, to ask you to report the bugs that you find. |
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 |
Please include the following in any report, |
together. |
|
|
|
You have to send us a test case that makes it possible for us to reproduce the |
@itemize @bullet |
bug. Include instructions on how to run the test case. |
@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 |
@item |
printed are incorrect and in that case, in what way. |
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 |
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 |
compiler; the GMP code tends to explore interesting corners in compilers. |
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}. |
|
|
|
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 |
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 |
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. |
the language needs to be improved, please send a note to the same address. |
Line 573 the language needs to be improved, please send a note |
|
Line 1163 the language needs to be improved, please send a note |
|
@chapter Integer Functions |
@chapter Integer Functions |
@cindex 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_}. |
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 |
@menu |
* Initializing Integers:: |
* Initializing Integers:: |
* Assigning Integers:: |
* Assigning Integers:: |
* Simultaneous Integer Init & Assign:: |
* Simultaneous Integer Init & Assign:: |
* Converting Integers:: |
* Converting Integers:: |
* Integer Arithmetic:: |
* Integer Arithmetic:: |
* Comparison Functions:: |
* Integer Division:: |
* Integer Logic and Bit Fiddling:: |
* Integer Exponentiation:: |
* I/O of Integers:: |
* Integer Roots:: |
* Miscellaneous Integer Functions:: |
* Number Theoretic Functions:: |
|
* Integer Comparisons:: |
|
* Integer Logic and Bit Fiddling:: |
|
* I/O of Integers:: |
|
* Integer Random Numbers:: |
|
* Miscellaneous Integer Functions:: |
@end menu |
@end menu |
|
|
@node Initializing Integers, Assigning Integers, , Integer Functions |
@node Initializing Integers, Assigning Integers, Integer Functions, Integer Functions |
@comment node-name, next, previous, up |
@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 |
The functions for integer arithmetic assume that all integer objects are |
initialized. You do that by calling the function @code{mpz_init}. |
initialized. You do that by calling the function @code{mpz_init}. |
Line 652 Don't call @code{mpz_clear}! |
|
Line 1249 Don't call @code{mpz_clear}! |
|
|
|
@node Assigning Integers, Simultaneous Integer Init & Assign, Initializing Integers, Integer Functions |
@node Assigning Integers, Simultaneous Integer Init & Assign, Initializing Integers, Integer Functions |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
@subsection Assignment Functions |
@section Assignment Functions |
@cindex Integer assignment functions |
@cindex Integer assignment functions |
|
@cindex Assignment functions |
|
|
These functions assign new values to already initialized integers |
These functions assign new values to already initialized integers |
(@pxref{Initializing Integers}). |
(@pxref{Initializing Integers}). |
Line 677 assumed, otherwise decimal is assumed. |
|
Line 1275 assumed, otherwise decimal is assumed. |
|
|
|
This function returns 0 if the entire string up to the '\0' is a valid |
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. |
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 |
@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 |
@node Simultaneous Integer Init & Assign, Converting Integers, Assigning Integers, Integer Functions |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
@subsection Combined Initialization and Assignment Functions |
@section Combined Initialization and Assignment Functions |
@cindex 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' |
which initialize the output and then store the value there. These functions' |
names have the form @code{mpz_init_set@dots{}} |
names have the form @code{mpz_init_set@dots{}} |
|
|
Line 726 an error occurs. (I.e., you have to call @code{mpz_cl |
|
Line 1337 an error occurs. (I.e., you have to call @code{mpz_cl |
|
@end deftypefun |
@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 |
@comment node-name, next, previous, up |
@section Conversion Functions |
@section Conversion Functions |
@cindex Integer conversion functions |
@cindex Integer conversion functions |
@cindex Conversion functions |
@cindex Conversion functions |
|
|
This section describes functions for converting arbitrary precision integers |
This section describes functions for converting GMP integers to standard C |
to standard C types. Functions for converting @emph{to} arbitrary |
types. Functions for converting @emph{to} GMP integers are described in |
precision integers are described in @ref{Assigning Integers} and @ref{I/O of |
@ref{Assigning Integers} and @ref{I/O of Integers}. |
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}) |
@deftypefun {unsigned long int} mpz_get_ui (mpz_t @var{op}) |
Return the least significant part from @var{op}. This function combined |
Return the least significant part from @var{op}. This function combined with |
with @* @code{mpz_tdiv_q_2exp(@dots{}, @var{op}, CHAR_BIT*sizeof(unsigned |
@* @code{mpz_tdiv_q_2exp(@dots{}, @var{op}, CHAR_BIT*sizeof(unsigned long |
long int))} can be used to extract the limbs of an integer. |
int))} can be used to decompose an integer into unsigned longs. |
@end deftypefun |
@end deftypefun |
|
|
@deftypefun {signed long int} mpz_get_si (mpz_t @var{op}) |
@deftypefun {signed long int} mpz_get_si (mpz_t @var{op}) |
Line 749 Otherwise return the least significant part of @var{op |
|
Line 1367 Otherwise return the least significant part of @var{op |
|
as @var{op}. |
as @var{op}. |
|
|
If @var{op} is too large to fit in a @code{signed long int}, the returned |
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 |
result is probably not very useful. To find out if the value will fit, use |
@c the function @code{mpz_fits_si}. |
the function @code{mpz_fits_slong_p}. |
@end deftypefun |
@end deftypefun |
|
|
@deftypefun double mpz_get_d (mpz_t @var{op}) |
@deftypefun double mpz_get_d (mpz_t @var{op}) |
Line 761 Convert @var{op} to a double. |
|
Line 1379 Convert @var{op} to a double. |
|
Convert @var{op} to a string of digits in base @var{base}. The base may vary |
Convert @var{op} to a string of digits in base @var{base}. The base may vary |
from 2 to 36. |
from 2 to 36. |
|
|
If @var{str} is NULL, space for the result string is allocated using the |
If @var{str} is @code{NULL}, space for the result string is allocated using the |
default allocation function, and a pointer to the string is returned. |
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 |
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 |
@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 |
extra bytes are for a possible minus sign, and for the terminating null |
character. |
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 |
@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 |
@comment node-name, next, previous, up |
@section Arithmetic Functions |
@section Arithmetic Functions |
@cindex Integer arithmetic functions |
@cindex Integer arithmetic functions |
|
|
|
|
@deftypefun void mpz_add (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) |
@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}) |
@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}. |
Set @var{rop} to @var{op1} + @var{op2}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Set @var{rop} to $@var{op1} + @var{op2}$. |
Set @var{rop} to $@var{op1} + @var{op2}$. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_sub (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) |
@deftypefun void mpz_sub (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) |
Line 796 Set @var{rop} to @var{op1} @minus{} @var{op2}. |
|
Line 1416 Set @var{rop} to @var{op1} @minus{} @var{op2}. |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_mul (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) |
@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}) |
@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}. |
Set @var{rop} to @var{op1} times @var{op2}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Set @var{rop} to $@var{op1} \times @var{op2}$. |
Set @var{rop} to $@var{op1} \times @var{op2}$. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@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}) |
@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 |
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. |
also be defined as a left shift, @var{op2} steps. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Set @var{rop} to $@var{op1} \times 2^{op2}$. This operation can also be |
Set @var{rop} to $@var{op1} \times 2^{op2}$. This operation can also be |
defined as a left shift, @var{op2} steps. |
defined as a left shift, @var{op2} steps. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_neg (mpz_t @var{rop}, mpz_t @var{op}) |
@deftypefun void mpz_neg (mpz_t @var{rop}, mpz_t @var{op}) |
Line 828 Set @var{rop} to @minus{}@var{op}. |
|
Line 1455 Set @var{rop} to @minus{}@var{op}. |
|
Set @var{rop} to the absolute value of @var{op}. |
Set @var{rop} to the absolute value of @var{op}. |
@end deftypefun |
@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 |
Division is undefined if the divisor is zero, and passing a zero divisor to the |
the divide or modulo functions, as well passing a zero mod argument 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 |
@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 |
intentionally divide by zero. This lets the user handle arithmetic exceptions |
arithmetic exceptions in these functions in the same manner as other |
in these functions in the same manner as other arithmetic exceptions. |
arithmetic exceptions. |
|
|
|
There are three main groups of division functions: |
There are three main groups of division functions: |
@itemize @bullet |
@itemize @bullet |
@item |
@item |
Functions that truncate the quotient towards 0. The names of these |
Functions that truncate the quotient towards 0. The names of these functions |
functions start with @code{mpz_tdiv}. The @samp{t} in the name is short for |
start with @code{mpz_tdiv}. The @samp{t} in the name is short for |
@samp{truncate}. |
@samp{truncate}. |
@item |
@item |
Functions that round the quotient towards @minus{}infinity. The names of |
Functions that round the quotient towards |
these routines start with @code{mpz_fdiv}. The @samp{f} in the name is |
@ifnottex |
short for @samp{floor}. |
@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 |
@item |
Functions that round the quotient towards +infinity. The names of |
Functions that round the quotient towards |
these routines start with @code{mpz_cdiv}. The @samp{c} in the name is |
@ifnottex |
short for @samp{ceil}. |
+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 |
@end itemize |
|
|
For each rounding mode, there are a couple of variants. Here @samp{q} means |
For each rounding mode, there are a couple of variants. Here @samp{q} means |
Line 862 that the quotient is computed, while @samp{r} means th |
|
Line 1501 that the quotient is computed, while @samp{r} means th |
|
computed. Functions that compute both the quotient and remainder have |
computed. Functions that compute both the quotient and remainder have |
@samp{qr} in the name. |
@samp{qr} in the name. |
|
|
@deftypefun void mpz_tdiv_q (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) |
@deftypefun void mpz_tdiv_q (mpz_t @var{q}, mpz_t @var{n}, mpz_t @var{d}) |
@deftypefunx void mpz_tdiv_q_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) |
@deftypefunx {unsigned long int} mpz_tdiv_q_ui (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d}) |
Set @var{rop} to [@var{op1}/@var{op2}]. The quotient is truncated towards |
Set @var{q} to [@var{n}/@var{d}], truncated towards 0. |
0. |
|
@end deftypefun |
|
|
|
@deftypefun void mpz_tdiv_r (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) |
The function @code{mpz_tdiv_q_ui} returns the absolute value of the true |
@deftypefunx void mpz_tdiv_r_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) |
remainder. |
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. |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_tdiv_qr (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, mpz_t @var{op2}) |
@deftypefun void mpz_tdiv_r (mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d}) |
@deftypefunx void mpz_tdiv_qr_ui (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, unsigned long int @var{op2}) |
@deftypefunx {unsigned long int} mpz_tdiv_r_ui (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) |
Divide @var{op1} by @var{op2} and put the quotient in @var{rop1} and the |
@ifnottex |
remainder in @var{rop2}. The quotient is rounded towards 0. Unless the |
Set @var{r} to (@var{n} - [@var{n}/@var{d}] * @var{d}), where the quotient is |
remainder is zero, it has the same sign as the dividend. |
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 |
The function @code{mpz_tdiv_r_ui} returns the absolute value of the remainder. |
undefined. |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_fdiv_q (mpz_t @var{rop1}, mpz_t @var{op1}, mpz_t @var{op2}) |
@deftypefun void mpz_tdiv_qr (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d}) |
@deftypefunx void mpz_fdiv_q_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) |
@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}) |
@ifinfo |
@ifnottex |
Set @var{rop} to @var{op1}/@var{op2}. The quotient is rounded towards |
Set @var{q} to [@var{n}/@var{d}], truncated towards 0. Set @var{r} to (@var{n} |
@minus{}infinity. |
- [@var{n}/@var{d}] * @var{d}). Unless @var{r} becomes zero, it will get the |
@end ifinfo |
same sign as @var{n}. If @var{q} and @var{r} are the same variable, the |
@iftex |
results are undefined. |
|
@end ifnottex |
@tex |
@tex |
Set @var{rop} to $\lfloor@var{op1}/@var{op2}\rfloor$. (I.e., round |
Set @var{q} to [@var{n}/@var{d}], truncated towards 0. Set @var{r} to $(@var{n} |
the quotient towards $-\infty$.) |
- [@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 tex |
@end iftex |
|
|
The function @code{mpz_tdiv_qr_ui} returns the absolute value of the remainder. |
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_fdiv_r (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) |
@deftypefun {unsigned long int} mpz_tdiv_ui (mpz_t @var{n}, unsigned long int @var{d}) |
@deftypefunx {unsigned long int} mpz_fdiv_r_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) |
Like @code{mpz_tdiv_r_ui}, but the remainder is not stored anywhere; its |
Divide @var{op1} by @var{op2} and put the remainder in @var{rop}. Unless |
absolute value is just returned. |
the remainder is zero, it has the same sign as the divisor. |
@end deftypefun |
|
|
For @code{mpz_fdiv_r_ui} the remainder is small enough to fit in an |
@deftypefun void mpz_fdiv_q (mpz_t @var{q}, mpz_t @var{n}, mpz_t @var{d}) |
@code{unsigned long int}, and is therefore returned. |
@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 |
@end deftypefun |
|
|
@deftypefun void mpz_fdiv_qr (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, mpz_t @var{op2}) |
@deftypefun void mpz_fdiv_r (mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d}) |
@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}) |
@deftypefunx {unsigned long int} mpz_fdiv_r_ui (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) |
Divide @var{op1} by @var{op2} and put the quotient in @var{rop1} and the |
@ifnottex |
remainder in @var{rop2}. The quotient is rounded towards @minus{}infinity. |
Set @var{r} to (@var{n} - @var{n}/@var{d} * @var{d}), where the quotient is |
Unless the remainder is zero, it has the same sign as the divisor. |
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 |
The function @code{mpz_fdiv_r_ui} returns the remainder. |
@code{unsigned long int}, and is therefore returned. |
@end deftypefun |
|
|
If @var{rop1} and @var{rop2} are the same variable, the results are |
@deftypefun void mpz_fdiv_qr (mpz_t @var{q}, mpz_t @var{r}, mpz_t @var{n}, mpz_t @var{d}) |
undefined. |
@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 |
@end deftypefun |
|
|
@deftypefun {unsigned long int} mpz_fdiv_ui (mpz_t @var{op1}, unsigned long int @var{op2}) |
@deftypefun {unsigned long int} mpz_fdiv_ui (mpz_t @var{n}, unsigned long int @var{d}) |
This function is similar to @code{mpz_fdiv_r_ui}, but the remainder is only |
Like @code{mpz_fdiv_r_ui}, but the remainder is not stored anywhere; it is just |
returned; it is not stored anywhere. |
returned. |
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_cdiv_q (mpz_t @var{rop1}, mpz_t @var{op1}, mpz_t @var{op2}) |
@deftypefun void mpz_cdiv_q (mpz_t @var{q}, mpz_t @var{n}, mpz_t @var{d}) |
@deftypefunx void mpz_cdiv_q_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) |
@deftypefunx {unsigned long int} mpz_cdiv_q_ui (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d}) |
@ifinfo |
@ifnottex |
Set @var{rop} to @var{op1}/@var{op2}. The quotient is rounded towards |
Set @var{q} to @var{n}/@var{d}, rounded towards +infinity. |
+infinity. |
@end ifnottex |
@end ifinfo |
|
@iftex |
|
@tex |
@tex |
Set @var{rop} to $\lceil@var{op1}/@var{op2}\rceil$. (I.e., round the |
Set @var{q} to $\lceil@var{n}/@var{d}\rceil$. |
quotient towards $+\infty$.) |
|
@end tex |
@end tex |
@end iftex |
|
|
The function @code{mpz_cdiv_q_ui} returns the negated remainder. |
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_cdiv_r (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) |
@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{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) |
@deftypefunx {unsigned long int} mpz_cdiv_r_ui (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) |
Divide @var{op1} by @var{op2} and put the remainder in @var{rop}. Unless |
@ifnottex |
the remainder is zero, it has the opposite sign as the divisor. |
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 |
The function @code{mpz_cdiv_r_ui} returns the negated remainder. |
@code{unsigned long int}, and it is therefore returned. |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_cdiv_qr (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, mpz_t @var{op2}) |
@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{rop1}, mpz_t @var{rop2}, mpz_t @var{op1}, unsigned long int @var{op2}) |
@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}) |
Divide @var{op1} by @var{op2} and put the quotient in @var{rop1} and the |
@ifnottex |
remainder in @var{rop2}. The quotient is rounded towards +infinity. Unless |
Set @var{q} to @var{n}/@var{d}, rounded towards +infinity. Set @var{r} |
the remainder is zero, it has the opposite sign as the divisor. |
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 |
The function @code{mpz_cdiv_qr_ui} returns the negated remainder. |
@code{unsigned long int}, and it is therefore returned. |
|
|
|
If @var{rop1} and @var{rop2} are the same variable, the results are |
|
undefined. |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun {unsigned long int} mpz_cdiv_ui (mpz_t @var{op1}, unsigned long int @var{op2}) |
@deftypefun {unsigned long int} mpz_cdiv_ui (mpz_t @var{n}, unsigned long int @var{d}) |
Return the negated remainder, similar to @code{mpz_cdiv_r_ui}. (The |
Like @code{mpz_tdiv_r_ui}, but the remainder is not stored anywhere; its |
difference is that this function doesn't store the remainder anywhere.) |
negated value is just returned. |
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_mod (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) |
@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{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) |
@deftypefunx {unsigned long int} mpz_mod_ui (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) |
Set @var{rop} to @var{op1} @code{mod} @var{op2}. The sign of the divisor is |
Set @var{r} to @var{n} @code{mod} @var{d}. The sign of the divisor is ignored; |
ignored, and the result is always non-negative. |
the result is always non-negative. |
|
|
For @code{mpz_mod_ui} the remainder is small enough to fit in an |
The function @code{mpz_mod_ui} returns the remainder. |
@code{unsigned long int}, and is therefore returned. |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_divexact (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) |
@deftypefun void mpz_divexact (mpz_t @var{q}, mpz_t @var{n}, mpz_t @var{d}) |
Set @var{rop} to @var{op1}/@var{op2}. This function produces correct |
@cindex Exact division functions |
results only when it is known in advance that @var{op2} divides |
Set @var{q} to @var{n}/@var{d}. This function produces correct results only |
@var{op1}. |
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 |
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 |
the quotient (@pxref{References} Jebelean), it is the best choice for instances |
instances in which exact division is known to occur, such as reducing a |
in which exact division is known to occur, such as reducing a rational to |
rational to lowest terms. |
lowest terms. |
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_tdiv_q_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) |
@deftypefun void mpz_tdiv_q_2exp (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d}) |
@ifinfo |
@cindex Bit shift right |
Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}. The quotient is |
@ifnottex |
rounded towards 0. |
Set @var{q} to @var{n} divided by 2 raised to @var{d}. The quotient is truncated |
@end ifinfo |
towards 0. |
@iftex |
@end ifnottex |
@tex |
@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 tex |
@end iftex |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_tdiv_r_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) |
@deftypefun void mpz_tdiv_r_2exp (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) |
@ifinfo |
@ifnottex |
Divide @var{op1} by (2 raised to @var{op2}) and put the remainder in |
Divide @var{n} by (2 raised to @var{d}), rounding the quotient towards 0, and |
@var{rop}. Unless it is zero, @var{rop} will have the same sign as @var{op1}. |
put the remainder in @var{r}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Divide @var{op1} by $2^{op2}$ and put the remainder in @var{rop}. Unless it is |
Set @var{r} to $n - [n / 2^{d}] \times 2^{d}$, where [ ] indicates rounding towards |
zero, @var{rop} will have the same sign as @var{op1}. |
0. |
@end tex |
@end tex |
@end iftex |
Unless it is zero, @var{r} will have the same sign as @var{n}. |
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_fdiv_q_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) |
@deftypefun void mpz_fdiv_q_2exp (mpz_t @var{q}, mpz_t @var{n}, unsigned long int @var{d}) |
@ifinfo |
@ifnottex |
Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}. The quotient is |
Set @var{q} to @var{n} divided by 2 raised to @var{d}, rounded towards |
rounded towards @minus{}infinity. |
@minus{}infinity. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Set @var{rop} to $\lfloor@var{op1}/2^{op2}\rfloor$. The quotient is rounded |
Set @var{q} to $\lfloor{n}/2^{d}\rfloor$. |
towards $-\infty$. |
|
@end tex |
@end tex |
@end iftex |
This operation can also be defined as arithmetic right shift @var{d} bit |
|
positions. |
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_fdiv_r_2exp (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) |
@deftypefun void mpz_fdiv_r_2exp (mpz_t @var{r}, mpz_t @var{n}, unsigned long int @var{d}) |
@ifinfo |
@ifnottex |
Divide @var{op1} by (2 raised to @var{op2}) and put the remainder in |
Divide @var{n} by (2 raised to @var{d}), rounding the quotient towards |
@var{rop}. The sign of @var{rop} will always be positive. |
@minus{}infinity, and put the remainder in @var{r}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Divide @var{op1} by $2^{op2}$ and put the remainder in @var{rop}. The sign of |
Set @var{r} to $n - \lfloor{n}/2^{d}\rfloor \times 2^{d}$. |
@var{rop} will always be positive. |
|
@end tex |
@end tex |
@end iftex |
The sign of @var{r} will always be positive. |
|
This operation can also be defined as masking of the @var{d} least significant |
This operation can also be defined as masking of the @var{op2} least |
bits. |
significant bits. |
|
@end deftypefun |
@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}) |
@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}) |
@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 |
Set @var{rop} to (@var{base} raised to @var{exp}) @code{mod} @var{mod}. If |
@var{exp} is negative, the result is undefined. |
@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 |
@end deftypefun |
|
|
@deftypefun void mpz_pow_ui (mpz_t @var{rop}, mpz_t @var{base}, unsigned long int @var{exp}) |
@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}) |
@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}. |
@ifnottex |
@ifinfo |
Set @var{rop} to @var{base} raised to @var{exp}. The case of 0^0 yields 1. |
The case of 0^0 yields 1. |
@end ifnottex |
@end ifinfo |
|
@iftex |
|
@tex |
@tex |
The case of $0^0$ yields 1. |
Set @var{rop} to $base^{exp}$. The case of $0^0$ yields 1. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@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}) |
@deftypefun void mpz_sqrt (mpz_t @var{rop}, mpz_t @var{op}) |
@ifinfo |
@ifnottex |
Set @var{rop} to the truncated integer part of the square root of |
Set @var{rop} to the truncated integer part of the square root of @var{op}. |
@var{op}. |
@end ifnottex |
@end ifinfo |
|
@iftex |
|
@tex |
@tex |
Set @var{rop} to $\lfloor\sqrt{@var{op}}\rfloor$, the truncated integer |
Set @var{rop} to $\lfloor\sqrt{@var{op}}\rfloor$, the truncated integer part of |
part of the square root of @var{op}. |
the square root of @var{op}. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_sqrtrem (mpz_t @var{rop1}, mpz_t @var{rop2}, mpz_t @var{op}) |
@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}, |
Set @var{rop1} to the truncated integer part of the square root of @var{op}, |
like @code{mpz_sqrt}. Set @var{rop2} to |
like @code{mpz_sqrt}. Set @var{rop2} to |
@var{op}@minus{}@var{rop1}*@var{rop1}, |
@var{op}@minus{}@var{rop1}*@var{rop1}, |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Set @var{rop1} to $\lfloor\sqrt{@var{op}}\rfloor$, like @code{mpz_sqrt}. |
Set @var{rop1} to $\lfloor\sqrt{@var{op}}\rfloor$, like @code{mpz_sqrt}. |
Set @var{rop2} to $(@var{op} - @var{rop1}^2)$, |
Set @var{rop2} to $(@var{op} - @var{rop1}^2)$, |
@end tex |
@end tex |
@end iftex |
|
(i.e., zero if @var{op} is a perfect square). |
(i.e., zero if @var{op} is a perfect square). |
|
|
If @var{rop1} and @var{rop2} are the same variable, the results are |
If @var{rop1} and @var{rop2} are the same variable, the results are |
undefined. |
undefined. |
@end deftypefun |
@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}) |
@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 |
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. |
@var{op} is an integer. Return zero otherwise. |
@end deftypefun |
@end deftypefun |
|
|
@subsection Number Theoretic Functions |
|
|
|
@deftypefun int mpz_probab_prime_p (mpz_t @var{op}, int @var{reps}) |
@need 2000 |
@ifinfo |
@node Number Theoretic Functions, Integer Comparisons, Integer Roots, Integer Functions |
If this function returns 0, @var{op} is definitely not prime. If it returns |
@section Number Theoretic Functions |
1, then @var{op} is `probably' prime. The probability of a false positive is |
@cindex Number theoretic functions |
(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. |
|
|
|
An implementation of the probabilistic primality test found in Seminumerical |
@deftypefun int mpz_probab_prime_p (mpz_t @var{n}, int @var{reps}) |
Algorithms (@pxref{References} Knuth). |
@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 |
@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}) |
@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}. |
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 |
@end deftypefun |
|
|
@deftypefun {unsigned long int} mpz_gcd_ui (mpz_t @var{rop}, mpz_t @var{op1}, unsigned long int @var{op2}) |
@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 |
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 |
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 |
returned. If the result does not fit, 0 is returned, and the result is equal |
|
|
@end deftypefun |
@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}) |
@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} + |
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 |
@var{b}@var{t} = @var{g} = @code{gcd}(@var{a}, @var{b}). If @var{t} is |
NULL, that argument is not computed. |
@code{NULL}, that argument is not computed. |
@end deftypefun |
@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}) |
@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 |
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 |
@var{rop}. Return non-zero if an inverse exists, zero otherwise. When the |
function returns zero, do not assume anything about the value in @var{rop}. |
function returns zero, @var{rop} is undefined. |
@end deftypefun |
@end deftypefun |
|
|
@deftypefun int mpz_jacobi (mpz_t @var{op1}, mpz_t @var{op2}) |
@deftypefun int mpz_jacobi (mpz_t @var{op1}, mpz_t @var{op2}) |
@deftypefunx int mpz_legendre (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 |
@end deftypefun |
|
|
@need 2000 |
@deftypefun int mpz_si_kronecker (long @var{a}, mpz_t @var{b}); |
@node Comparison Functions, Integer Logic and Bit Fiddling, Integer Arithmetic, Integer Functions |
@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 |
@comment node-name, next, previous, up |
@section Comparison Functions |
@section Comparison Functions |
|
@cindex Integer comparison functions |
|
@cindex Comparison functions |
|
|
@deftypefun int mpz_cmp (mpz_t @var{op1}, mpz_t @var{op2}) |
@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} > |
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}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} < |
@var{op2}. |
@var{op2}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} > |
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}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1} |
< @var{op2}$. |
< @var{op2}$. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefn Macro int mpz_cmp_ui (mpz_t @var{op1}, unsigned long int @var{op2}) |
@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}) |
@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} > |
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}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} < |
@var{op2}. |
@var{op2}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} > |
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}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1} |
< @var{op2}$. |
< @var{op2}$. |
@end tex |
@end tex |
@end iftex |
|
|
|
These functions are actually implemented as macros. They evaluate their |
These functions are actually implemented as macros. They evaluate their |
arguments multiple times. |
arguments multiple times. |
@end deftypefn |
@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}) |
@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. |
Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$. |
Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$. |
@end tex |
@end tex |
@end iftex |
|
|
|
This function is actually implemented as a macro. It evaluates its |
This function is actually implemented as a macro. It evaluates its |
arguments multiple times. |
arguments multiple times. |
@end deftypefn |
@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 |
@comment node-name, next, previous, up |
@section Logical and Bit Manipulation Functions |
@section Logical and Bit Manipulation Functions |
@cindex Logical functions |
@cindex Logical functions |
@cindex Bit manipulation functions |
@cindex Bit manipulation functions |
|
@cindex Integer bit manipulation functions |
|
|
These functions behave as if two's complement arithmetic were used (although |
These functions behave as if two's complement arithmetic were used (although |
sign-magnitude is used by the actual implementation). |
sign-magnitude is used by the actual implementation). |
Line 1221 Set @var{rop} to @var{op1} logical-and @var{op2}. |
|
Line 2025 Set @var{rop} to @var{op1} logical-and @var{op2}. |
|
Set @var{rop} to @var{op1} inclusive-or @var{op2}. |
Set @var{rop} to @var{op1} inclusive-or @var{op2}. |
@end deftypefun |
@end deftypefun |
|
|
@c @deftypefun void mpz_xor (mpz_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}) |
@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}. |
Set @var{rop} to @var{op1} exclusive-or @var{op2}. |
@c @end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_com (mpz_t @var{rop}, mpz_t @var{op}) |
@deftypefun void mpz_com (mpz_t @var{rop}, mpz_t @var{op}) |
Set @var{rop} to the one's complement of @var{op}. |
Set @var{rop} to the one's complement of @var{op}. |
Line 1242 between the two operands. Otherwise, return the large |
|
Line 2046 between the two operands. Otherwise, return the large |
|
It is possible to extend this function to return a useful value when the |
It is possible to extend this function to return a useful value when the |
operands are both negative, but the current implementation returns |
operands are both negative, but the current implementation returns |
@var{MAX_ULONG} in this case. @strong{Do not depend on this behavior, since |
@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 |
@end deftypefun |
|
|
@deftypefun {unsigned long int} mpz_scan0 (mpz_t @var{op}, unsigned long int @var{starting_bit}) |
@deftypefun {unsigned long int} mpz_scan0 (mpz_t @var{op}, unsigned long int @var{starting_bit}) |
Line 1256 bits, until the first set bit is found. Return the in |
|
Line 2060 bits, until the first set bit is found. Return the in |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpz_setbit (mpz_t @var{rop}, unsigned long int @var{bit_index}) |
@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 |
@end deftypefun |
|
|
@deftypefun void mpz_clrbit (mpz_t @var{rop}, unsigned long int @var{bit_index}) |
@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 |
@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 |
@comment node-name, next, previous, up |
@section Input and Output Functions |
@section Input and Output Functions |
@cindex Integer input and output functions |
@cindex Integer input and output functions |
Line 1272 Clear bit @var{bit_index} in @var{op1}. |
|
Line 2080 Clear bit @var{bit_index} in @var{op1}. |
|
@cindex I/O functions |
@cindex I/O functions |
|
|
Functions that perform input from a stdio stream, and functions that output to |
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 |
these functions will make them read from @code{stdin} and write to |
@code{stdout}, respectively. |
@code{stdout}, respectively. |
|
|
|
|
|
|
|
|
@need 2000 |
@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 |
@comment node-name, next, previous, up |
@section Miscellaneous Functions |
@section Random Number Functions |
@cindex Miscellaneous integer 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}) |
@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 |
Generate a random integer of at most @var{max_size} limbs. The generated |
random number doesn't satisfy any particular requirements of randomness. |
random number doesn't satisfy any particular requirements of randomness. |
Negative random numbers are generated when @var{max_size} is negative. |
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 |
@end deftypefun |
|
|
@deftypefun void mpz_random2 (mpz_t @var{rop}, mp_size_t @var{max_size}) |
@deftypefun void mpz_random2 (mpz_t @var{rop}, mp_size_t @var{max_size}) |
Line 1341 of zeros and ones in the binary representation. Usefu |
|
Line 2208 of zeros and ones in the binary representation. Usefu |
|
and algorithms, since this kind of random numbers have proven to be more |
and algorithms, since this kind of random numbers have proven to be more |
likely to trigger corner-case bugs. Negative random numbers are generated |
likely to trigger corner-case bugs. Negative random numbers are generated |
when @var{max_size} is negative. |
when @var{max_size} is negative. |
|
|
|
This function is obsolete. Use @code{mpz_rrandomb} instead. |
@end deftypefun |
@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}) |
@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, |
Return the size of @var{op} measured in number of limbs. If @var{op} is zero, |
the returned value will be zero. |
the returned value will be zero. |
@c (@xref{Nomenclature}, for an explanation of the concept @dfn{limb}.) |
@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 |
@end deftypefun |
|
|
@deftypefun size_t mpz_sizeinbase (mpz_t @var{op}, int @var{base}) |
@deftypefun size_t mpz_sizeinbase (mpz_t @var{op}, int @var{base}) |
Line 1369 minus sign and one for the terminating '\0'). |
|
Line 2260 minus sign and one for the terminating '\0'). |
|
@chapter Rational Number Functions |
@chapter Rational Number Functions |
@cindex 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_}. |
numbers. These functions start with the prefix @code{mpq_}. |
|
|
Rational numbers are stored in objects of type @code{mpq_t}. |
Rational numbers are stored in objects of type @code{mpq_t}. |
Line 1390 Remove any factors that are common to the numerator an |
|
Line 2281 Remove any factors that are common to the numerator an |
|
@end deftypefun |
@end deftypefun |
|
|
@menu |
@menu |
* Initializing Rationals:: |
* Initializing Rationals:: |
* Assigning Rationals:: |
* Rational Arithmetic:: |
* Simultaneous Integer Init & Assign:: |
* Comparing Rationals:: |
* Comparing Rationals:: |
* Applying Integer Functions:: |
* Applying Integer Functions:: |
* I/O of Rationals:: |
* Miscellaneous Rational Functions:: |
* Miscellaneous Rational Functions:: |
@end menu |
@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 |
@comment node-name, next, previous, up |
@section Initialization and Assignment Functions |
@section Initialization and Assignment Functions |
|
@cindex Initialization and assignment functions |
|
@cindex Rational init and assign |
|
|
@deftypefun void mpq_init (mpq_t @var{dest_rational}) |
@deftypefun void mpq_init (mpq_t @var{dest_rational}) |
Initialize @var{dest_rational} and set it to 0/1. Each variable should |
Initialize @var{dest_rational} and set it to 0/1. Each variable should |
Line 1425 Set the value of @var{rop} to @var{op1}/@var{op2}. No |
|
Line 2318 Set the value of @var{rop} to @var{op1}/@var{op2}. No |
|
@code{mpq_canonicalize} before any operations are performed on @var{rop}. |
@code{mpq_canonicalize} before any operations are performed on @var{rop}. |
@end deftypefun |
@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 |
@comment node-name, next, previous, up |
@section Arithmetic Functions |
@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}) |
@deftypefun void mpq_add (mpq_t @var{sum}, mpq_t @var{addend1}, mpq_t @var{addend2}) |
Set @var{sum} to @var{addend1} + @var{addend2}. |
Set @var{sum} to @var{addend1} + @var{addend2}. |
Line 1438 Set @var{difference} to @var{minuend} @minus{} @var{su |
|
Line 2338 Set @var{difference} to @var{minuend} @minus{} @var{su |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpq_mul (mpq_t @var{product}, mpq_t @var{multiplier}, mpq_t @var{multiplicand}) |
@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}. |
Set @var{product} to @var{multiplier} times @var{multiplicand}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Set @var{product} to $@var{multiplier} \times @var{multiplicand}$. |
Set @var{product} to $@var{multiplier} \times @var{multiplicand}$. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpq_div (mpq_t @var{quotient}, mpq_t @var{dividend}, mpq_t @var{divisor}) |
@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}. |
Set @var{quotient} to @var{dividend}/@var{divisor}. |
@end deftypefun |
@end deftypefun |
|
|
Line 1461 Set @var{inverted_number} to 1/@var{number}. If the n |
|
Line 2360 Set @var{inverted_number} to 1/@var{number}. If the n |
|
zero, this routine will divide by zero. |
zero, this routine will divide by zero. |
@end deftypefun |
@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 |
@comment node-name, next, previous, up |
@section Comparison Functions |
@section Comparison Functions |
|
@cindex Rational comparison functions |
|
@cindex Comparison functions |
|
|
@deftypefun int mpq_cmp (mpq_t @var{op1}, mpq_t @var{op2}) |
@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} > |
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}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} < |
@var{op2}. |
@var{op2}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} > |
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}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1} |
< @var{op2}$. |
< @var{op2}$. |
@end tex |
@end tex |
@end iftex |
|
|
|
To determine if two rationals are equal, @code{mpq_equal} is faster than |
To determine if two rationals are equal, @code{mpq_equal} is faster than |
@code{mpq_cmp}. |
@code{mpq_cmp}. |
@end deftypefun |
@end deftypefun |
|
|
@deftypefn Macro int mpq_cmp_ui (mpq_t @var{op1}, unsigned long int @var{num2}, unsigned long int @var{den2}) |
@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 |
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}, |
@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}. |
and a negative value if @var{op1} < @var{num2}/@var{den2}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Compare @var{op1} and @var{num2}/@var{den2}. Return a positive value if |
Compare @var{op1} and @var{num2}/@var{den2}. Return a positive value if |
$@var{op1} > @var{num2}/@var{den2}$, zero if $@var{op1} = |
$@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}$, and a negative value if $@var{op1} < |
@var{num2}/@var{den2}$. |
@var{num2}/@var{den2}$. |
@end tex |
@end tex |
@end iftex |
|
|
|
This routine allows that @var{num2} and @var{den2} have common factors. |
This routine allows that @var{num2} and @var{den2} have common factors. |
|
|
Line 1505 arguments multiple times. |
|
Line 2402 arguments multiple times. |
|
@end deftypefn |
@end deftypefn |
|
|
@deftypefn Macro int mpq_sgn (mpq_t @var{op}) |
@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. |
Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$. |
Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$. |
@end tex |
@end tex |
@end iftex |
|
|
|
This function is actually implemented as a macro. It evaluates its |
This function is actually implemented as a macro. It evaluates its |
arguments multiple times. |
arguments multiple times. |
Line 1524 non-equal. Although @code{mpq_cmp} can be used for th |
|
Line 2419 non-equal. Although @code{mpq_cmp} can be used for th |
|
function is much faster. |
function is much faster. |
@end deftypefun |
@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 |
@comment node-name, next, previous, up |
@section Applying Integer Functions to Rationals |
@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 |
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 |
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, |
number. If these macros are used to assign to the rational number, |
Line 1540 Return a reference to the numerator and denominator of |
|
Line 2437 Return a reference to the numerator and denominator of |
|
The @code{mpz} functions can be used on the result of these macros. |
The @code{mpz} functions can be used on the result of these macros. |
@end deftypefn |
@end deftypefn |
|
|
|
|
@need 2000 |
@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 |
@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 |
@section Miscellaneous Functions |
|
@cindex Rational miscellaneous functions |
|
@cindex Miscellaneous rational functions |
|
|
@deftypefun double mpq_get_d (mpq_t @var{op}) |
@deftypefun double mpq_get_d (mpq_t @var{op}) |
Convert @var{op} to a double. |
Convert @var{op} to a double. |
@end deftypefun |
@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 |
These functions assign between either the numerator or denominator of a |
rational, and an integer. Instead of using these functions, it is preferable |
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}, |
to use the more general mechanisms @code{mpq_numref} and @code{mpq_denref}, |
Line 1600 This function is equivalent to |
|
Line 2531 This function is equivalent to |
|
@cindex Floating-point functions |
@cindex Floating-point functions |
@cindex Float functions |
@cindex Float functions |
|
|
This is a description of the @emph{preliminary} interface for floating-point |
This chapter describes the GMP functions for performing floating point |
arithmetic in GNU MP 2. |
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 |
integer functions. The function prefix for floating-point operations is |
@code{mpf_}. |
@code{mpf_}. |
|
|
There is one significant characteristic of floating-point numbers that has |
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 |
classes: the inherent inexactness of floating point arithmetic. The user has |
to specify the precision of each variable. A computation that assigns a |
to specify the precision of each variable. A computation that assigns a |
variable will take place with the precision of the assigned variable; the |
variable will take place with the precision of the assigned variable; the |
precision of variables used as input is ignored. |
precision of variables used as input is ignored. |
|
|
@cindex User-defined precision |
@cindex User-defined precision |
|
@cindex Precision of floats |
The precision of a calculation is defined as follows: Compute the requested |
The precision of a calculation is defined as follows: Compute the requested |
operation exactly (with ``infinite precision''), and truncate the result to |
operation exactly (with ``infinite precision''), and truncate the result to |
the destination variable precision. Even if the user has asked for a very |
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 |
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 |
precision of the result will be limited to what is required to represent the |
result accurately. |
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 |
to the IEEE P754 arithmetic. Specifically, the results obtained on one |
computer often differs from the results obtained on a computer with a |
computer often differs from the results obtained on a computer with a |
different word size. |
different word size. |
|
|
@menu |
@menu |
* Initializing Floats:: |
* Initializing Floats:: |
* Assigning Floats:: |
* Assigning Floats:: |
* Simultaneous Float Init & Assign:: |
* Simultaneous Float Init & Assign:: |
* Converting Floats:: |
* Converting Floats:: |
* Float Arithmetic:: |
* Float Arithmetic:: |
* Float Comparison:: |
* Float Comparison:: |
* I/O of Floats:: |
* I/O of Floats:: |
* Miscellaneous Float Functions:: |
* Miscellaneous Float Functions:: |
@end menu |
@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 |
@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}) |
@deftypefun void mpf_set_default_prec (unsigned long int @var{prec}) |
Set the default precision to be @strong{at least} @var{prec} bits. All |
Set the default precision to be @strong{at least} @var{prec} bits. All |
Line 1707 Set the precision of @var{rop} to be @strong{at least} |
|
Line 2641 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} |
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 |
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 |
@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 |
@end deftypefun |
|
|
|
|
|
@need 2000 |
@node Assigning Floats, Simultaneous Float Init & Assign, Initializing Floats, Floating-point Functions |
@node Assigning Floats, Simultaneous Float Init & Assign, Initializing Floats, Floating-point Functions |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
@subsection Assignment Functions |
@section Assignment Functions |
@cindex Float assignment functions |
@cindex Float assignment functions |
|
@cindex Assignment functions |
|
|
These functions assign new values to already initialized floats |
These functions assign new values to already initialized floats |
(@pxref{Initializing Floats}). |
(@pxref{Initializing Floats}). |
Line 1743 Unlike the corresponding @code{mpz} function, the base |
|
Line 2680 Unlike the corresponding @code{mpz} function, the base |
|
from the leading characters of the string if @var{base} is 0. This is so that |
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. |
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 |
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. |
in base @var{base}. Otherwise it returns @minus{}1. |
@end deftypefun |
@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 |
@node Simultaneous Float Init & Assign, Converting Floats, Assigning Floats, Floating-point Functions |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
@subsection Combined Initialization and Assignment Functions |
@section Combined Initialization and Assignment Functions |
@cindex 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' |
which initialize the output and then store the value there. These functions' |
names have the form @code{mpf_init_set@dots{}} |
names have the form @code{mpf_init_set@dots{}} |
|
|
Line 1789 set by @code{mpf_set_default_prec}. |
|
Line 2737 set by @code{mpf_set_default_prec}. |
|
@node Converting Floats, Float Arithmetic, Simultaneous Float Init & Assign, Floating-point Functions |
@node Converting Floats, Float Arithmetic, Simultaneous Float Init & Assign, Floating-point Functions |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
@section Conversion Functions |
@section Conversion Functions |
|
@cindex Float conversion functions |
@cindex Conversion functions |
@cindex Conversion functions |
|
|
@deftypefun double mpf_get_d (mpf_t @var{op}) |
@deftypefun double mpf_get_d (mpf_t @var{op}) |
Line 1801 from 2 to 36. Generate at most @var{n_digits} signifi |
|
Line 2750 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{n_digits} is 0, the maximum number of digits accurately representable by |
@var{op}. |
@var{op}. |
|
|
If @var{str} is NULL, space for the mantissa is allocated using the default |
If @var{str} is @code{NULL}, space for the mantissa is allocated using the default |
allocation function, and a pointer to the string is returned. |
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 |
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. |
possible minus sign, and for the terminating null character. |
|
|
Line 1813 The exponent is written through the pointer @var{exppt |
|
Line 2762 The exponent is written through the pointer @var{exppt |
|
If @var{n_digits} is 0, the maximum number of digits meaningfully achievable |
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 |
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 |
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. |
whenever @var{n_digits} is 0. |
|
|
The generated string is a fraction, with an implicit radix point immediately |
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 |
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}. |
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 |
@end deftypefun |
|
|
|
|
Line 1830 returned as "31416" in the string and 1 written at @va |
|
Line 2782 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}) |
@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}) |
@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}. |
Set @var{rop} to @var{op1} + @var{op2}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Set @var{rop} to $@var{op1} + @var{op2}$. |
Set @var{rop} to $@var{op1} + @var{op2}$. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpf_sub (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2}) |
@deftypefun void mpf_sub (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2}) |
Line 1848 Set @var{rop} to @var{op1} @minus{} @var{op2}. |
|
Line 2798 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}) |
@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}) |
@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}. |
Set @var{rop} to @var{op1} times @var{op2}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Set @var{rop} to $@var{op1} \times @var{op2}$. |
Set @var{rop} to $@var{op1} \times @var{op2}$. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@end deftypefun |
|
|
Division is undefined if the divisor is zero, and passing a zero divisor to |
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. |
the divide functions will make these functions intentionally divide by zero. |
This gives the user the possibility to handle arithmetic exceptions in these |
This lets the user handle arithmetic exceptions in these functions in the same |
functions in the same manner as other arithmetic exceptions. |
manner as other arithmetic exceptions. |
|
|
@deftypefun void mpf_div (mpf_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2}) |
@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_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}) |
@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}. |
Set @var{rop} to @var{op1}/@var{op2}. |
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpf_sqrt (mpf_t @var{rop}, mpf_t @var{op}) |
@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}) |
@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}. |
Set @var{rop} to the square root of @var{op}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Set @var{rop} to $\sqrt{@var{op}}$. |
Set @var{rop} to $\sqrt{@var{op}}$. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@end deftypefun |
|
|
@c @deftypefun void mpf_pow_ui (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2}) |
@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}. |
@cindex Exponentiation functions |
@c @end deftypefun |
@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}) |
@deftypefun void mpf_neg (mpf_t @var{rop}, mpf_t @var{op}) |
Set @var{rop} to @minus{}@var{op}. |
Set @var{rop} to @minus{}@var{op}. |
Line 1894 Set @var{rop} to the absolute value of @var{op}. |
|
Line 2848 Set @var{rop} to the absolute value of @var{op}. |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpf_mul_2exp (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2}) |
@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}. |
Set @var{rop} to @var{op1} times 2 raised to @var{op2}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Set @var{rop} to $@var{op1} \times 2^{op2}$. |
Set @var{rop} to $@var{op1} \times 2^{op2}$. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void mpf_div_2exp (mpf_t @var{rop}, mpf_t @var{op1}, unsigned long int @var{op2}) |
@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}. |
Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Set @var{rop} to $@var{op1}/2^{op2}$. |
Set @var{rop} to $@var{op1}/2^{op2}$. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@end deftypefun |
|
|
@node Float Comparison, I/O of Floats, Float Arithmetic, Floating-point Functions |
@node Float Comparison, I/O of Floats, Float Arithmetic, Floating-point Functions |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
@section Comparison Functions |
@section Comparison Functions |
@cindex Float comparisons functions |
@cindex Float comparison functions |
@cindex Comparison functions |
@cindex Comparison functions |
|
|
@deftypefun int mpf_cmp (mpf_t @var{op1}, mpf_t @var{op2}) |
@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_ui (mpf_t @var{op1}, unsigned long int @var{op2}) |
@deftypefunx int mpf_cmp_si (mpf_t @var{op1}, signed 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} > |
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}, zero if @var{op1} = @var{op2}, and a negative value if @var{op1} < |
@var{op2}. |
@var{op2}. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Compare @var{op1} and @var{op2}. Return a positive value if $@var{op1} > |
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}$, zero if $@var{op1} = @var{op2}$, and a negative value if $@var{op1} |
< @var{op2}$. |
< @var{op2}$. |
@end tex |
@end tex |
@end iftex |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun int mpf_eq (mpf_t @var{op1}, mpf_t @var{op2}, unsigned long int op3) |
@deftypefun int mpf_eq (mpf_t @var{op1}, mpf_t @var{op2}, unsigned long int op3) |
Line 1950 result in @var{rop}. |
|
Line 2898 result in @var{rop}. |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefn Macro int mpf_sgn (mpf_t @var{op}) |
@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. |
Return +1 if @var{op} > 0, 0 if @var{op} = 0, and @minus{}1 if @var{op} < 0. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$. |
Return $+1$ if $@var{op} > 0$, 0 if $@var{op} = 0$, and $-1$ if $@var{op} < 0$. |
@end tex |
@end tex |
@end iftex |
|
|
|
This function is actually implemented as a macro. It evaluates its |
This function is actually implemented as a macro. It evaluates its |
arguments multiple times. |
arguments multiple times. |
Line 1972 arguments multiple times. |
|
Line 2918 arguments multiple times. |
|
@cindex I/O functions |
@cindex I/O functions |
|
|
Functions that perform input from a stdio stream, and functions that output to |
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 |
these functions will make them read from @code{stdin} and write to |
@code{stdout}, respectively. |
@code{stdout}, respectively. |
|
|
Line 2026 Return the number of bytes read, or if an error occurr |
|
Line 2972 Return the number of bytes read, or if an error occurr |
|
@c @end deftypefun |
@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 |
@comment node-name, next, previous, up |
@section Miscellaneous Functions |
@section Miscellaneous Functions |
@cindex Miscellaneous float 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}) |
@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 |
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 |
zeros and ones in the binary representation. The exponent of the number is in |
Line 2040 proven to be more likely to trigger corner-case bugs. |
|
Line 3004 proven to be more likely to trigger corner-case bugs. |
|
are generated when @var{max_size} is negative. |
are generated when @var{max_size} is negative. |
@end deftypefun |
@end deftypefun |
|
|
|
|
|
|
@c @deftypefun size_t mpf_size (mpf_t @var{op}) |
@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 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 zero, the returned value will be zero. (@xref{Nomenclature}, for an |
@c explanation of the concept @dfn{limb}.) |
@c explanation of the concept @dfn{limb}.) |
@c |
@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 releases.} |
@c @end deftypefun |
@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 |
@comment node-name, next, previous, up |
@chapter Low-level Functions |
@chapter Low-level Functions |
@cindex Low-level functions |
@cindex Low-level functions |
|
|
This chapter describes low-level MP functions, used to implement the high-level |
This chapter describes low-level GMP functions, used to implement the high-level |
MP functions, but also intended for time-critical user code. |
GMP functions, but also intended for time-critical user code. |
|
|
These functions start with the prefix @code{mpn_}. |
These functions start with the prefix @code{mpn_}. |
|
|
Line 2077 With this way of specifying operands, it is possible t |
|
Line 3043 With this way of specifying operands, it is possible t |
|
on subranges of an argument, and store the result into a subrange of a |
on subranges of an argument, and store the result into a subrange of a |
destination. |
destination. |
|
|
A common requirement for all functions is that each source area needs at least |
A common requirement for all functions is that each source area needs at |
one limb. No size argument may be zero. |
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_}, |
The @code{mpn} functions are the base for the implementation of the |
@code{mpf_}, and @code{mpq_} functions. |
@code{mpz_}, @code{mpf_}, and @code{mpq_} functions. |
|
|
This example adds the number beginning at @var{src1_ptr} and the number |
This example adds the number beginning at @var{s1p} and the number |
beginning at @var{src2_ptr} and writes the sum at @var{dest_ptr}. All areas |
beginning at @var{s2p} and writes the sum at @var{destp}. All areas |
have @var{size} limbs. |
have @var{size} limbs. |
|
|
@example |
@example |
cy = mpn_add_n (dest_ptr, src1_ptr, src2_ptr, size) |
cy = mpn_add_n (destp, s1p, s2p, size) |
@end example |
@end example |
|
|
@noindent |
@noindent |
In the notation used here, a source operand is identified by the pointer to |
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, |
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}) |
@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{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@}, and |
Add @{@var{s1p}, @var{size}@} and @{@var{s2p}, @var{size}@}, and |
write the @var{size} least significant limbs of the result to @var{dest_ptr}. |
write the @var{size} least significant limbs of the result to @var{rp}. |
Return carry, either 0 or 1. |
Return carry, either 0 or 1. |
|
|
This is the lowest-level function for addition. It is the preferred function |
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 |
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. |
@code{mpn_lshift} with a count of 1 for optimal speed. |
@end deftypefun |
@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}) |
@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{src1_ptr}, @var{size}@} and @var{src2_limb}, and write the |
Add @{@var{s1p}, @var{size}@} and @var{s2limb}, and write the |
@var{size} least significant limbs of the result to @var{dest_ptr}. Return |
@var{size} least significant limbs of the result to @var{rp}. Return |
carry, either 0 or 1. |
carry, either 0 or 1. |
@end deftypefun |
@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}) |
@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{src1_ptr}, @var{src1_size}@} and @{@var{src2_ptr}, |
Add @{@var{s1p}, @var{s1size}@} and @{@var{s2p}, |
@var{src2_size}@}, and write the @var{src1_size} least significant limbs of |
@var{s2size}@}, and write the @var{s1size} least significant limbs of |
the result to @var{dest_ptr}. Return carry, either 0 or 1. |
the result to @var{rp}. Return carry, either 0 or 1. |
|
|
This function requires that @var{src1_size} is greater than or equal to |
This function requires that @var{s1size} is greater than or equal to |
@var{src2_size}. |
@var{s2size}. |
@end deftypefun |
@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}) |
@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{src2_ptr}, @var{src2_size}@} from @{@var{src1_ptr}, |
Subtract @{@var{s2p}, @var{s2size}@} from @{@var{s1p}, |
@var{size}@}, and write the @var{size} least significant limbs of the result |
@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 |
This is the lowest-level function for subtraction. It is the preferred |
function for subtraction, since it is written in assembly for most targets. |
function for subtraction, since it is written in assembly for most targets. |
@end deftypefun |
@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}) |
@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{src2_limb} from @{@var{src1_ptr}, @var{size}@}, and write the |
Subtract @var{s2limb} from @{@var{s1p}, @var{size}@}, and write the |
@var{size} least significant limbs of the result to @var{dest_ptr}. Return |
@var{size} least significant limbs of the result to @var{rp}. Return |
borrow, either 0 or 1. |
borrow, either 0 or 1. |
@end deftypefun |
@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}) |
@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{src2_ptr}, @var{src2_size}@} from @{@var{src1_ptr}, |
Subtract @{@var{s2p}, @var{s2size}@} from @{@var{s1p}, |
@var{src1_size}@}, and write the @var{src1_size} least significant limbs of |
@var{s1size}@}, and write the @var{s1size} least significant limbs of |
the result to @var{dest_ptr}. Return borrow, either 0 or 1. |
the result to @var{rp}. Return borrow, either 0 or 1. |
|
|
This function requires that @var{src1_size} is greater than or equal to |
This function requires that @var{s1size} is greater than or equal to |
@var{src2_size}. |
@var{s2size}. |
@end deftypefun |
@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}) |
@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{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@}, |
Multiply @{@var{s1p}, @var{size}@} and @{@var{s2p}, @var{size}@}, |
and write the @strong{entire} result to @var{dest_ptr}. |
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. |
significant result might be one limb smaller. |
@end deftypefun |
@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}) |
@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{src1_ptr}, @var{size}@} and @var{src2_limb}, and write the |
Multiply @{@var{s1p}, @var{size}@} and @var{s2limb}, and write the |
@var{size} least significant limbs of the product to @var{dest_ptr}. Return |
@var{size} least significant limbs of the product to @var{rp}. Return |
the most significant limb of the product. |
the most significant limb of the product. |
|
|
This is a low-level function that is a building block for general |
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. |
for most targets. |
|
|
Don't call this function if @var{src2_limb} is a power of 2; use |
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{src2_limb} |
@code{mpn_lshift} with a count equal to the logarithm of @var{s2limb} |
instead, for optimal speed. |
instead, for optimal speed. |
@end deftypefun |
@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}) |
@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{src1_ptr}, @var{size}@} and @var{src2_limb}, and add the |
Multiply @{@var{s1p}, @var{size}@} and @var{s2limb}, and add the |
@var{size} least significant limbs of the product to @{@var{dest_ptr}, |
@var{size} least significant limbs of the product to @{@var{rp}, |
@var{size}@} and write the result to @var{dest_ptr} @var{dest_ptr}. Return |
@var{size}@} and write the result to @var{rp}. Return |
the most significant limb of the product, plus carry-out from the addition. |
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 |
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. |
for most targets. |
@end deftypefun |
@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}) |
@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{src1_ptr}, @var{size}@} and @var{src2_limb}, and subtract the |
Multiply @{@var{s1p}, @var{size}@} and @var{s2limb}, and subtract the |
@var{size} least significant limbs of the product from @{@var{dest_ptr}, |
@var{size} least significant limbs of the product from @{@var{rp}, |
@var{size}@} and write the result to @var{dest_ptr}. Return the most |
@var{size}@} and write the result to @var{rp}. Return the most |
significant limb of the product, minus borrow-out from the subtraction. |
significant limb of the product, minus borrow-out from the subtraction. |
|
|
This is a low-level function that is a building block for general |
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. |
in assembly for most targets. |
@end deftypefun |
@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}) |
@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{src1_ptr}, @var{src1_size}@} and @{@var{src2_ptr}, |
Multiply @{@var{s1p}, @var{s1size}@} and @{@var{s2p}, |
@var{src2_size}@}, and write the result to @var{dest_ptr}. Return the most |
@var{s2size}@}, and write the result to @var{rp}. Return the most |
significant limb of the result. |
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. |
limbs, even if the result might be one limb smaller. |
|
|
This function requires that @var{src1_size} is greater than or equal to |
This function requires that @var{s1size} is greater than or equal to |
@var{src2_size}. The destination must be distinct from either input operands. |
@var{s2size}. The destination must be distinct from either input operands. |
@end deftypefun |
@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}) |
@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{rs2p}, @var{rs2size}@} by @{@var{s3p}, @var{s3size}@}, and |
Divide @{@var{np}, @var{nn}@} by @{@var{dp}, @var{dn}@}. Write the quotient |
write the quotient at @var{r1p}, with the exception of the most significant |
at @var{qp} and the remainder at @var{rp}. |
limb, which is returned. The remainder replaces the dividend at @var{rs2p}. |
|
|
|
|
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, |
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 |
and stored after the integral limbs. For most usages, @var{xsize} will be |
zero. |
zero. |
Line 2223 The area at @var{r1p} needs to be @var{rs2size} @minus |
|
Line 3210 The area at @var{r1p} needs to be @var{rs2size} @minus |
|
@var{xsize} limbs large. |
@var{xsize} limbs large. |
@end deftypefun |
@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 |
Divide @{@var{s2p}, @var{s2size}@} by @var{s3limb}, and write the quotient |
at @var{r1p}. Return the remainder. |
at @var{r1p}. Return the remainder. |
|
|
In addition to an integer quotient, @var{xsize} fraction limbs are developed, |
The integer quotient is written to @{@var{r1p}+@var{xsize}, @var{s2size}@} and |
and stored after the integral limbs. For most usages, @var{xsize} will be |
in addition @var{xsize} fraction limbs are developed and written to |
zero. |
@{@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 |
The areas at @var{r1p} and @var{s2p} have to be identical or completely |
separate, not partially overlapping. |
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. |
@strong{This interface is obsolete. It will disappear from future releases. |
Use @code{mpn_divrem} in its stead.} |
Use @code{mpn_divrem} in its stead.} |
@end deftypefun |
@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}) |
@deftypefn Macro mp_limb_t mpn_divexact_by3 (mp_limb_t *@var{rp}, mp_limb_t *@var{sp}, @w{mp_size_t @var{size}}) |
@strong{This interface is obsolete. It will disappear from future releases. |
@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}) |
Use @code{mpn_divrem_1} in its stead.} |
Divide @{@var{sp}, @var{size}@} by 3, expecting it to divide exactly, and |
@end deftypefun |
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. |
Divide @{@var{s1p}, @var{s1size}@} by @var{s2limb}, and return the remainder. |
|
@var{s1size} can be zero. |
@end deftypefun |
@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. |
@strong{This interface is obsolete. It will disappear from future releases. |
Use @code{mpn_mod_1} in its stead.} |
Use @code{mpn_mod_1} in its stead.} |
@end deftypefun |
@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 |
The function puts the low [@var{d}/@var{BITS_PER_MP_LIMB}] limbs of |
@var{q} = |
@var{q} = |
@{@var{s1p}, @var{s1size}@}/@{@var{s2p}, @var{s2size}@} |
@{@var{s1p}, @var{s1size}@}/@{@var{s2p}, @var{s2size}@} |
mod 2^@var{d} |
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}. |
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}@} |
@{@var{s1p}, @var{s1size}@} - @var{q} * @{@var{s2p}, @var{s2size}@} |
Line 2268 is placed at @var{s1p}. |
|
Line 3305 is placed at @var{s1p}. |
|
Since the low [@var{d}/@var{BITS_PER_MP_LIMB}] limbs of |
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 |
this difference are zero, it is possible to overwrite the low limbs at |
@var{s1p} with this difference, |
@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}, |
This function requires that @var{s1size} * @var{BITS_PER_MP_LIMB} >= @var{D}, |
and that @{@var{s2p}, @var{s2size}@} is odd. |
and that @{@var{s2p}, @var{s2size}@} is odd. |
Line 2277 and that @{@var{s2p}, @var{s2size}@} is odd. |
|
Line 3314 and that @{@var{s2p}, @var{s2size}@} is odd. |
|
future revisions.} |
future revisions.} |
@end deftypefun |
@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 |
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 |
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. |
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 |
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. |
This function is written in assembly for most targets. |
@end deftypefun |
@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 |
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 |
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. |
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 |
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. |
This function is written in assembly for most targets. |
@end deftypefun |
@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}) |
@deftypefun int mpn_cmp (const mp_limb_t *@var{s1p}, const mp_limb_t *@var{s2p}, mp_size_t @var{size}) |
Compare @{@var{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@} and |
Compare @{@var{s1p}, @var{size}@} and @{@var{s2p}, @var{size}@} and |
return a positive value if src1 > src2, 0 of they are equal, and a negative |
return a positive value if s1 > src2, 0 of they are equal, and a negative |
value if src1 < src2. |
value if s1 < src2. |
@end deftypefun |
@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}) |
@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{dest_ptr} the greatest common divisor of @{@var{src1_ptr}, |
Puts at @var{rp} the greatest common divisor of @{@var{s1p}, |
@var{src1_size}@} and @{@var{src2_ptr}, @var{src2_size}@}; both source |
@var{s1size}@} and @{@var{s2p}, @var{s2size}@}; both source |
operands are destroyed by the operation. The size in limbs of the greatest |
operands are destroyed by the operation. The size in limbs of the greatest |
common divisor is returned. |
common divisor is returned. |
|
|
@{@var{src1_ptr}, @var{src1_size}@} must be odd, and @{@var{src2_ptr}, |
@{@var{s1p}, @var{s1size}@} must have at least as many bits as |
@var{src2_size}@} must have at least as many bits as @{@var{src1_ptr}, |
@{@var{s2p}, @var{s2size}@}, and @{@var{s2p}, @var{s2size}@} must be odd. |
@var{src1_size}@}. |
|
|
|
@strong{This interface is preliminary. It might change incompatibly in |
|
future revisions.} |
|
@end deftypefun |
@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}) |
@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{src1_ptr}, @var{src1_size}@} |
Return the greatest common divisor of @{@var{s1p}, @var{s1size}@} |
and @var{src2_limb}, where @var{src2_limb} (as well as @var{src1_size}) |
and @var{s2limb}, where @var{s2limb} (as well as @var{s1size}) |
must be different from 0. |
must be different from 0. |
@end deftypefun |
@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}) |
@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}) |
Puts at @var{r1p} the greatest common divisor of @{@var{s1p}, @var{s1size}@} |
Compute the greatest common divisor of @{@var{s1p}, @var{s1size}@} and |
and @{@var{s2p}, @var{s2size}@}. The first cofactor is written at |
@{@var{s2p}, @var{s2size}@}. Store the gcd at @var{r1p} and return its size |
@var{r2p}. Both source operands are destroyed by the operation. The size |
in limbs. Write the first cofactor at @var{r2p} and store its size in |
in limbs of the greatest common divisor is returned. |
*@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 |
@{@var{s1p}, @var{s1size}@} must be greater than or equal to @{@var{s2p}, |
future revisions.} |
@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 |
@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 |
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. |
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 |
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 |
@var{r2p} and @var{sp} have to be identical or completely separate, not |
partially overlapping. |
partially overlapping. |
|
|
@ifinfo |
@ifnottex |
The area at @var{r1p} needs to have space for ceil(@var{size}/2) limbs. |
The area at @var{r1p} needs to have space for ceil(@var{size}/2) limbs. |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
The area at @var{r1p} needs to have space for $\lceil@var{size}/2\rceil$ limbs. |
The area at @var{r1p} needs to have space for $\lceil@var{size}/2\rceil$ limbs. |
@end tex |
@end tex |
@end iftex |
|
The area at @var{r2p} needs to be @var{size} limbs large. |
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 |
@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 |
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, |
@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 |
add the ASCII codes for @samp{0} or @samp{A}, depending on the base and |
Line 2376 The area at @var{str} has to have space for the larges |
|
Line 3407 The area at @var{str} has to have space for the larges |
|
represented by a @var{s1size} long limb array, plus one extra character. |
represented by a @var{s1size} long limb array, plus one extra character. |
@end deftypefun |
@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 |
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 |
a limb array @{@var{s1p}, @var{s1size}@}. The base of @var{str} is |
@var{base}. |
@var{base}. |
Line 2384 a limb array @{@var{s1p}, @var{s1size}@}. The base of |
|
Line 3415 a limb array @{@var{s1p}, @var{s1size}@}. The base of |
|
Return the number of limbs stored in @var{r1p}. |
Return the number of limbs stored in @var{r1p}. |
@end deftypefun |
@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. |
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 |
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. |
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 |
@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. |
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 |
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. |
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 |
@end deftypefun |
|
|
@deftypefun void mpn_random2 (mp_limb_t * @var{r1p}, mp_size_t @var{r1size}) |
@deftypefun void mpn_random (mp_limb_t *@var{r1p}, mp_size_t @var{r1size}) |
Generate a random number of length @var{r1size} with long strings of zeros |
@deftypefunx void mpn_random2 (mp_limb_t *@var{r1p}, mp_size_t @var{r1size}) |
and ones in the binary representation, and store it at @var{r1p}. |
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 |
@code{mpn_random2} is intended for testing the correctness of the @code{mpn} |
implementation of the @code{mpn} routines. |
routines. |
@end deftypefun |
@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}@}. |
Count the number of set bits in @{@var{s1p}, @var{size}@}. |
@end deftypefun |
@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 |
Compute the hamming distance between @{@var{s1p}, @var{size}@} and |
@{@var{s2p}, @var{size}@}. |
@{@var{s2p}, @var{size}@}. |
@end deftypefun |
@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. |
Return non-zero iff @{@var{s1p}, @var{size}@} is a perfect square. |
@end deftypefun |
@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 |
@comment node-name, next, previous, up |
@chapter Berkeley MP Compatible Functions |
@chapter Berkeley MP Compatible Functions |
|
@cindex Berkeley MP compatible functions |
@cindex BSD MP compatible functions |
@cindex BSD MP compatible functions |
|
|
These functions are intended to be fully compatible with the Berkeley MP |
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 |
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 |
same variable as both source and destination in a single function call. The |
Line 2447 with @code{pow} in @file{libm.a}. |
|
Line 3633 with @code{pow} in @file{libm.a}. |
|
@cindex @file{mp.h} |
@cindex @file{mp.h} |
Include the header @file{mp.h} to get the definition of the necessary types |
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 |
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<dir> option to the compiler, |
This means that you probably need to give the -I<dir> option to the compiler, |
where <dir> is the directory where you have GNU @file{mp.h}. |
where <dir> is the directory where you have GNU @file{mp.h}. |
|
|
Line 2493 negative arguments. |
|
Line 3679 negative arguments. |
|
@end deftypefun |
@end deftypefun |
|
|
@deftypefun void msqrt (MINT *@var{operand}, MINT *@var{root}, MINT *@var{remainder}) |
@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 |
Set @var{root} to the truncated integer part of the square root of |
@var{operand}. Set @var{remainder} to |
@var{operand}. Set @var{remainder} to |
@var{operand}@minus{}@var{root}*@var{root}, |
@var{operand}@minus{}@var{root}*@var{root}, |
@end ifinfo |
@end ifnottex |
@iftex |
|
@tex |
@tex |
Set @var{root} to $\lfloor\sqrt{@var{operand}}\rfloor$, like |
Set @var{root} to $\lfloor\sqrt{@var{operand}}\rfloor$, like |
@code{mpz_sqrt}. Set @var{remainder} to $(operand - root^2)$, |
@code{mpz_sqrt}. Set @var{remainder} to $(operand - root^2)$, |
@end tex |
@end tex |
@end iftex |
|
(i.e., zero if @var{operand} is a perfect square). |
(i.e., zero if @var{operand} is a perfect square). |
|
|
If @var{root} and @var{remainder} are the same variable, the results are |
If @var{root} and @var{remainder} are the same variable, the results are |
Line 2549 De-allocate, the space used by @var{operand}. @strong |
|
Line 3733 De-allocate, the space used by @var{operand}. @strong |
|
only be passed a value returned by @code{itom} or @code{xtom}.} |
only be passed a value returned by @code{itom} or @code{xtom}.} |
@end deftypefun |
@end deftypefun |
|
|
|
|
@node Custom Allocation, Contributors, BSD Compatible Functions, Top |
@node Custom Allocation, Contributors, BSD Compatible Functions, Top |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
@chapter Custom Allocation |
@chapter Custom Allocation |
|
@cindex Custom allocation |
|
@cindex Memory allocation |
|
@cindex Allocation of memory |
|
|
By default, the MP functions use @code{malloc}, @code{realloc}, and |
By default, GMP uses @code{malloc}, @code{realloc} and @code{free} for memory |
@code{free} for memory allocation. If @code{malloc} or @code{realloc} fails, |
allocation. If @code{malloc} or @code{realloc} fails, GMP prints a message to |
the MP library terminates execution after printing a fatal error message to |
the standard error output and terminates execution. |
standard error. |
|
|
|
For some applications, you may wish to allocate memory in other ways, or you |
Some applications might want to allocate memory in other ways, or might not |
may not want to have a fatal error when there is no more memory available. To |
want a fatal error when there is no more memory available. To accomplish |
accomplish this, you can specify alternative memory allocation functions. |
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)) |
@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 |
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 |
@strong{Be sure to call this function only when there are no active GMP |
MP objects that were allocated using the previously active allocation |
objects allocated using the previous memory functions! Usually, that means |
function! Usually, that means that you have to call this function before any |
that you have to call this function before any other GMP function.} |
other MP function.} |
|
@end deftypefun |
@end deftypefun |
|
|
The functions you supply should fit the following declarations: |
The functions you supply should fit the following declarations: |
Line 2605 the size of an object, normally an 8 bit byte.) |
|
Line 3794 the size of an object, normally an 8 bit byte.) |
|
@node Contributors, References, Custom Allocation, Top |
@node Contributors, References, Custom Allocation, Top |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
@unnumbered Contributors |
@unnumbered Contributors |
|
@cindex Contributors |
|
|
I would like to thank Gunnar Sjoedin and Hans Riesel for their help with |
Torbjorn Granlund wrote the original GMP library and is still developing and |
mathematical problems, Richard Stallman for his help with design issues and |
maintaining it. Several other individuals and organizations have contributed |
for revising the first version of this manual, Brian Beuning and Doug Lea for |
to GMP in various ways. Here is a list in chronological order: |
their testing of early versions of the library. |
|
|
|
|
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 |
John Amanatides of York University in Canada contributed the function |
@code{mpz_probab_prime_p}. |
@code{mpz_probab_prime_p}. |
|
|
Line 2621 Ken Weber (Kent State University, Universidade Federal |
|
Line 3819 Ken Weber (Kent State University, Universidade Federal |
|
contributed @code{mpz_gcd}, @code{mpz_divexact}, @code{mpn_gcd}, and |
contributed @code{mpz_gcd}, @code{mpz_divexact}, @code{mpn_gcd}, and |
@code{mpn_bdivmod}, partially supported by CNPq (Brazil) grant 301314194-2. |
@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 |
He has also made valuable suggestions and tested numerous intermediary |
releases. |
releases. |
|
|
Joachim Hollman was involved in the design of the @code{mpf} interface, and in |
Joachim Hollman was involved in the design of the @code{mpf} interface, and in |
the @code{mpz} design revisions for version 2. |
the @code{mpz} design revisions for version 2. |
|
|
Bennet Yee contributed the functions @code{mpz_jacobi} and |
Bennet Yee contributed the functions @code{mpz_jacobi} and @code{mpz_legendre}. |
@code{mpz_legendre}. |
|
|
|
Andreas Schwab contributed the files @file{mpn/m68k/lshift.S} and |
Andreas Schwab contributed the files @file{mpn/m68k/lshift.S} and |
@file{mpn/m68k/rshift.S}. |
@file{mpn/m68k/rshift.S}. |
|
|
The development of floating point functions of GNU MP 2, were supported in |
The development of floating point functions of GNU MP 2, were supported in part |
part by the ESPRIT-BRA (Basic Research Activities) 6846 project POSSO |
by the ESPRIT-BRA (Basic Research Activities) 6846 project POSSO (POlynomial |
(POlynomial System SOlving). |
System SOlving). |
|
|
GNU MP 2 was finished and released by TMG Datakonsult, Sodermannagatan 5, 116 |
GNU MP 2 was finished and released by SWOX AB (formerly known as TMG |
23 STOCKHOLM, SWEDEN, in cooperation with the IDA Center for Computing |
Datakonsult), Swedenborgsgatan 23, SE-118 27 STOCKHOLM, SWEDEN, in |
Sciences, USA. |
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 |
@comment node-name, next, previous, up |
@unnumbered References |
@unnumbered References |
|
@cindex References |
|
|
@itemize @bullet |
@itemize @bullet |
|
|
@item |
@item |
Donald E. Knuth, "The Art of Computer Programming", vol 2, |
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 |
@item |
John D. Lipson, "Elements of Algebra and Algebraic Computing", |
John D. Lipson, "Elements of Algebra and Algebraic Computing", |
The Benjamin Cummings Publishing Company Inc, 1981. |
The Benjamin Cummings Publishing Company Inc, 1981. |
|
|
@item |
@item |
Richard M. Stallman, "Using and Porting GCC", Free Software Foundation, |
Richard M. Stallman, "Using and Porting GCC", Free Software Foundation, 1999, |
1995. |
available online @uref{http://www.gnu.org/software/gcc/onlinedocs/}, and in |
|
the GCC package @uref{ftp://ftp.gnu.org/pub/gnu/gcc/}. |
|
|
@item |
@item |
Peter L. Montgomery, "Modular Multiplication Without Trial Division", in |
Peter L. Montgomery, "Modular Multiplication Without Trial Division", in |
Line 2668 Mathematics of Computation, volume 44, number 170, Apr |
|
Line 3900 Mathematics of Computation, volume 44, number 170, Apr |
|
@item |
@item |
Torbjorn Granlund and Peter L. Montgomery, "Division by Invariant |
Torbjorn Granlund and Peter L. Montgomery, "Division by Invariant |
Integers using Multiplication", in Proceedings of the SIGPLAN |
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 |
@item |
Tudor Jebelean, |
Tudor Jebelean, |
"An algorithm for exact division", |
"An algorithm for exact division", |
Journal of Symbolic Computation, |
Journal of Symbolic Computation, |
v. 15, 1993, pp. 169-180. |
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 |
@item |
Kenneth Weber, "The accelerated integer GCD algorithm", |
Kenneth Weber, "The accelerated integer GCD algorithm", |
ACM Transactions on Mathematical Software, |
ACM Transactions on Mathematical Software, |
v. 21 (March), 1995, pp. 111-122. |
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 |
@end itemize |
|
|
@node Concept Index, , , Top |
@node Concept Index, Function Index, References, Top |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
@unnumbered Concept Index |
@unnumbered Concept Index |
@printindex cp |
@printindex cp |
|
|
@node Function Index, , , Top |
@node Function Index, , Concept Index, Top |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
@unnumbered Function and Type Index |
@unnumbered Function and Type Index |
@printindex fn |
@printindex fn |
Line 2695 v. 21 (March), 1995, pp. 111-122. |
|
Line 3944 v. 21 (March), 1995, pp. 111-122. |
|
|
|
@contents |
@contents |
@bye |
@bye |
|
|
|
@c Local variables: |
|
@c fill-column: 78 |
|
@c End: |