mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-24 11:29:10 +00:00
1284 lines
50 KiB
Plaintext
1284 lines
50 KiB
Plaintext
|
This is Info file gmp.info, produced by Makeinfo-1.64 from the input
|
|||
|
file gmp.texi.
|
|||
|
|
|||
|
START-INFO-DIR-ENTRY
|
|||
|
* gmp: (gmp.info). GNU Multiple Precision Arithmetic Library.
|
|||
|
END-INFO-DIR-ENTRY
|
|||
|
|
|||
|
This file documents GNU MP, a library for arbitrary-precision
|
|||
|
arithmetic.
|
|||
|
|
|||
|
Copyright (C) 1991, 1993, 1994, 1995, 1996 Free Software Foundation,
|
|||
|
Inc.
|
|||
|
|
|||
|
Permission is granted to make and distribute verbatim copies of this
|
|||
|
manual provided the copyright notice and this permission notice are
|
|||
|
preserved on all copies.
|
|||
|
|
|||
|
Permission is granted to copy and distribute modified versions of
|
|||
|
this manual under the conditions for verbatim copying, provided that
|
|||
|
the entire resulting derived work is distributed under the terms of a
|
|||
|
permission notice identical to this one.
|
|||
|
|
|||
|
Permission is granted to copy and distribute translations of this
|
|||
|
manual into another language, under the above conditions for modified
|
|||
|
versions, except that this permission notice may be stated in a
|
|||
|
translation approved by the Foundation.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
|
|||
|
|
|||
|
GNU MP
|
|||
|
******
|
|||
|
|
|||
|
This manual documents how to install and use the GNU multiple
|
|||
|
precision arithmetic library, version 2.0.2.
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* Copying:: GMP Copying Conditions (LGPL).
|
|||
|
* Introduction to MP:: Brief introduction to GNU MP.
|
|||
|
* Installing MP:: How to configure and compile the MP library.
|
|||
|
* MP Basics:: What every MP user should now.
|
|||
|
* Reporting Bugs:: How to usefully report bugs.
|
|||
|
* Integer Functions:: Functions for arithmetic on signed integers.
|
|||
|
* Rational Number Functions:: Functions for arithmetic on rational numbers.
|
|||
|
* Floating-point Functions:: Functions for arithmetic on floats.
|
|||
|
* Low-level Functions:: Fast functions for natural numbers.
|
|||
|
* BSD Compatible Functions:: All functions found in BSD MP.
|
|||
|
* Custom Allocation:: How to customize the internal allocation.
|
|||
|
|
|||
|
* Contributors::
|
|||
|
* References::
|
|||
|
* Concept Index::
|
|||
|
* Function Index::
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Copying, Next: Introduction to MP, Prev: Top, Up: Top
|
|||
|
|
|||
|
GNU MP Copying Conditions
|
|||
|
*************************
|
|||
|
|
|||
|
This library is "free"; this means that everyone is free to use it
|
|||
|
and free to redistribute it on a free basis. The library is not in the
|
|||
|
public domain; it is copyrighted and there are restrictions on its
|
|||
|
distribution, but these restrictions are designed to permit everything
|
|||
|
that a good cooperating citizen would want to do. What is not allowed
|
|||
|
is to try to prevent others from further sharing any version of this
|
|||
|
library that they might get from you.
|
|||
|
|
|||
|
Specifically, we want to make sure that you have the right to give
|
|||
|
away copies of the library, that you receive source code or else can
|
|||
|
get it if you want it, that you can change this library or use pieces
|
|||
|
of it in new free programs, and that you know you can do these things.
|
|||
|
|
|||
|
To make sure that everyone has such rights, we have to forbid you to
|
|||
|
deprive anyone else of these rights. For example, if you distribute
|
|||
|
copies of the GNU MP library, you must give the recipients all the
|
|||
|
rights that you have. You must make sure that they, too, receive or
|
|||
|
can get the source code. And you must tell them their rights.
|
|||
|
|
|||
|
Also, for our own protection, we must make certain that everyone
|
|||
|
finds out that there is no warranty for the GNU MP library. If it is
|
|||
|
modified by someone else and passed on, we want their recipients to
|
|||
|
know that what they have is not what we distributed, so that any
|
|||
|
problems introduced by others will not reflect on our reputation.
|
|||
|
|
|||
|
The precise conditions of the license for the GNU MP library are
|
|||
|
found in the Library General Public License that accompany the source
|
|||
|
code.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Introduction to MP, Next: Installing MP, Prev: Copying, Up: Top
|
|||
|
|
|||
|
Introduction to GNU MP
|
|||
|
**********************
|
|||
|
|
|||
|
GNU MP is a portable library written in C for arbitrary precision
|
|||
|
arithmetic on integers, rational numbers, and floating-point numbers.
|
|||
|
It aims to provide the fastest possible arithmetic for all applications
|
|||
|
that need higher precision than is directly supported by the basic C
|
|||
|
types.
|
|||
|
|
|||
|
Many applications use just a few hundred bits of precision; but some
|
|||
|
applications may need thousands or even millions of bits. MP is
|
|||
|
designed to give good performance for both, by choosing algorithms
|
|||
|
based on the sizes of the operands, and by carefully keeping the
|
|||
|
overhead at a minimum.
|
|||
|
|
|||
|
The speed of MP is achieved by using fullwords as the basic
|
|||
|
arithmetic type, by using sophisticated algorithms, by including
|
|||
|
carefully optimized assembly code for the most common inner loops for
|
|||
|
many different CPUs, and by a general emphasis on speed (as opposed to
|
|||
|
simplicity or elegance).
|
|||
|
|
|||
|
There is carefully optimized assembly code for these CPUs: DEC
|
|||
|
Alpha, Amd 29000, HPPA 1.0 and 1.1, Intel Pentium and generic x86,
|
|||
|
Intel i960, Motorola MC68000, MC68020, MC88100, and MC88110,
|
|||
|
Motorola/IBM PowerPC, National NS32000, IBM POWER, MIPS R3000, R4000,
|
|||
|
SPARCv7, SuperSPARC, generic SPARCv8, and DEC VAX. Some optimizations
|
|||
|
also for ARM, Clipper, IBM ROMP (RT), and Pyramid AP/XP.
|
|||
|
|
|||
|
This version of MP is released under a more liberal license than
|
|||
|
previous versions. It is now permitted to link MP to non-free
|
|||
|
programs, as long as MP source code is provided when distributing the
|
|||
|
non-free program.
|
|||
|
|
|||
|
How to use this Manual
|
|||
|
======================
|
|||
|
|
|||
|
Everyone should read *Note MP Basics::. If you need to install the
|
|||
|
library yourself, you need to read *Note Installing MP::, too.
|
|||
|
|
|||
|
The rest of the manual can be used for later reference, although it
|
|||
|
is probably a good idea to glance through it.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Installing MP, Next: MP Basics, Prev: Introduction to MP, Up: Top
|
|||
|
|
|||
|
Installing MP
|
|||
|
*************
|
|||
|
|
|||
|
To build MP, you first have to configure it for your CPU and
|
|||
|
operating system. You need a C compiler, preferably GCC, but any
|
|||
|
reasonable compiler should work. And you need a standard Unix `make'
|
|||
|
program, plus some other standard Unix utility programs.
|
|||
|
|
|||
|
(If you're on an MS-DOS machine, your can build MP using `make.bat'.
|
|||
|
It requires that djgpp is installed. It does not require
|
|||
|
configuration, nor is `make' needed; `make.bat' both configures and
|
|||
|
builds the library.)
|
|||
|
|
|||
|
Here are the steps needed to install the library on Unix systems:
|
|||
|
|
|||
|
1. In most cases, `./configure --target=cpu-vendor-os', should work
|
|||
|
both for 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, and prefix the configure command with the path to the
|
|||
|
MP source directory. Not all `make' programs have the necessary
|
|||
|
features to support this. In particular, SunOS and Slowaris
|
|||
|
`make' have bugs that makes them unable to build from a separate
|
|||
|
object directory. Use GNU `make' instead.
|
|||
|
|
|||
|
In addition to the standard cpu-vendor-os tuples, MP recognizes
|
|||
|
sparc8 and supersparc as valid CPU names. Specifying these CPU
|
|||
|
names for relevant systems will improve performance significantly.
|
|||
|
|
|||
|
In general, if you want a library that runs as fast as possible,
|
|||
|
you should make sure you configure MP for the exact CPU type your
|
|||
|
system uses.
|
|||
|
|
|||
|
If you have `gcc' in your `PATH', it will be used by default. To
|
|||
|
override this, pass `-with-gcc=no' to `configure'.
|
|||
|
|
|||
|
2. `make'
|
|||
|
|
|||
|
This will compile MP, and create a library archive file `libgmp.a'
|
|||
|
in the working directory.
|
|||
|
|
|||
|
3. `make check'
|
|||
|
|
|||
|
This will make sure MP was built correctly. If you get error
|
|||
|
messages, please report this to `bug-gmp@prep.ai.mit.edu'. (*Note
|
|||
|
Reporting Bugs::, for information on what to include in useful bug
|
|||
|
reports.)
|
|||
|
|
|||
|
4. `make install'
|
|||
|
|
|||
|
This will copy the file `gmp.h' and `libgmp.a', as well as the info
|
|||
|
files, to `/usr/local' (or if you passed the `--prefix' option to
|
|||
|
`configure', to the directory given as argument to `--prefix').
|
|||
|
|
|||
|
If you wish to build and install the BSD MP compatible functions, use
|
|||
|
`make libmp.a' and `make install-bsdmp'.
|
|||
|
|
|||
|
There are some other useful make targets:
|
|||
|
|
|||
|
* `doc'
|
|||
|
|
|||
|
Create a DVI version of the manual, in `gmp.dvi' and a set of info
|
|||
|
files, in `gmp.info', `gmp.info-1', `gmp.info-2', etc.
|
|||
|
|
|||
|
* `ps'
|
|||
|
|
|||
|
Create a Postscript version of the manual, in `gmp.ps'.
|
|||
|
|
|||
|
* `html'
|
|||
|
|
|||
|
Create a HTML version of the manual, in `gmp.html'.
|
|||
|
|
|||
|
* `clean'
|
|||
|
|
|||
|
Delete all object files and archive files, but not the
|
|||
|
configuration files.
|
|||
|
|
|||
|
* `distclean'
|
|||
|
|
|||
|
Delete all files not included in the distribution.
|
|||
|
|
|||
|
* `uninstall'
|
|||
|
|
|||
|
Delete all files copied by `make install'.
|
|||
|
|
|||
|
Known Build Problems
|
|||
|
====================
|
|||
|
|
|||
|
GCC 2.7.2 (as well as 2.6.3) for the RS/6000 and PowerPC can not be
|
|||
|
used to compile MP, due to a bug in GCC. If you want to use GCC for
|
|||
|
these machines, you need to apply the patch below to GCC, or use a
|
|||
|
later version of the compiler.
|
|||
|
|
|||
|
If you are on a Sequent Symmetry, use the GNU assembler instead of
|
|||
|
the system's assembler, since the latter has serious bugs.
|
|||
|
|
|||
|
The system compiler on NeXT is a massacred and old gcc, even if the
|
|||
|
compiler calls itself `cc'. This compiler cannot be used to build MP.
|
|||
|
You need to get a real gcc, and install that before you compile MP.
|
|||
|
(NeXT might have fixed this in newer releases of their system.)
|
|||
|
|
|||
|
The system C compiler under SunOS 4 has a bug that makes it
|
|||
|
miscompile mpq/get_d.c. This will make `make check' fail.
|
|||
|
|
|||
|
Please report other problems to `bug-gmp@prep.ai.mit.edu'. *Note
|
|||
|
Reporting Bugs::.
|
|||
|
|
|||
|
Patch to apply to GCC 2.6.3 and 2.7.2:
|
|||
|
|
|||
|
*** config/rs6000/rs6000.md Sun Feb 11 08:22:11 1996
|
|||
|
--- config/rs6000/rs6000.md.new Sun Feb 18 03:33:37 1996
|
|||
|
***************
|
|||
|
*** 920,926 ****
|
|||
|
(set (match_operand:SI 0 "gpc_reg_operand" "=r")
|
|||
|
(not:SI (match_dup 1)))]
|
|||
|
""
|
|||
|
! "nor. %0,%2,%1"
|
|||
|
[(set_attr "type" "compare")])
|
|||
|
|
|||
|
(define_insn ""
|
|||
|
--- 920,926 ----
|
|||
|
(set (match_operand:SI 0 "gpc_reg_operand" "=r")
|
|||
|
(not:SI (match_dup 1)))]
|
|||
|
""
|
|||
|
! "nor. %0,%1,%1"
|
|||
|
[(set_attr "type" "compare")])
|
|||
|
|
|||
|
(define_insn ""
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: MP Basics, Next: Reporting Bugs, Prev: Installing MP, Up: Top
|
|||
|
|
|||
|
MP Basics
|
|||
|
*********
|
|||
|
|
|||
|
All declarations needed to use MP are collected in the include file
|
|||
|
`gmp.h'. It is designed to work with both C and C++ compilers.
|
|||
|
|
|||
|
Nomenclature and Types
|
|||
|
======================
|
|||
|
|
|||
|
In this manual, "integer" usually means a multiple precision integer, as
|
|||
|
defined by the MP library. The C data type for such integers is
|
|||
|
`mpz_t'. Here are some examples of how to declare such integers:
|
|||
|
|
|||
|
mpz_t sum;
|
|||
|
|
|||
|
struct foo { mpz_t x, y; };
|
|||
|
|
|||
|
mpz_t vec[20];
|
|||
|
|
|||
|
"Rational number" means a multiple precision fraction. The C data type
|
|||
|
for these fractions is `mpq_t'. For example:
|
|||
|
|
|||
|
mpq_t quotient;
|
|||
|
|
|||
|
"Floating point number" or "Float" for short, is an arbitrary precision
|
|||
|
mantissa with an limited precision exponent. The C data type for such
|
|||
|
objects is `mpf_t'.
|
|||
|
|
|||
|
A "limb" means the part of a multi-precision number that fits in a
|
|||
|
single word. (We chose this word because a limb of the human body is
|
|||
|
analogous to a digit, only larger, and containing several digits.)
|
|||
|
Normally a limb contains 32 or 64 bits. The C data type for a limb is
|
|||
|
`mp_limb_t'.
|
|||
|
|
|||
|
Function Classes
|
|||
|
================
|
|||
|
|
|||
|
There are six classes of functions in the MP library:
|
|||
|
|
|||
|
1. Functions for signed integer arithmetic, with names beginning with
|
|||
|
`mpz_'. The associated type is `mpz_t'. There are about 100
|
|||
|
functions in this class.
|
|||
|
|
|||
|
2. Functions for rational number arithmetic, with names beginning with
|
|||
|
`mpq_'. The associated type is `mpq_t'. There are about 20
|
|||
|
functions in this class, but the functions in the previous class
|
|||
|
can be used for performing arithmetic on the numerator and
|
|||
|
denominator separately.
|
|||
|
|
|||
|
3. Functions for floating-point arithmetic, with names beginning with
|
|||
|
`mpf_'. The associated type is `mpf_t'. There are about 50
|
|||
|
functions is this class.
|
|||
|
|
|||
|
4. Functions compatible with Berkeley MP, such as `itom', `madd', and
|
|||
|
`mult'. The associated type is `MINT'.
|
|||
|
|
|||
|
5. Fast low-level functions that operate on natural numbers. These
|
|||
|
are used by the functions in the preceding groups, and you can
|
|||
|
also call them directly from very time-critical user programs.
|
|||
|
These functions' names begin with `mpn_'. There are about 30
|
|||
|
(hard-to-use) functions in this class.
|
|||
|
|
|||
|
The associated type is array of `mp_limb_t'.
|
|||
|
|
|||
|
6. Miscellaneous functions. Functions for setting up custom
|
|||
|
allocation.
|
|||
|
|
|||
|
MP Variable Conventions
|
|||
|
=======================
|
|||
|
|
|||
|
As a general rule, all MP functions expect output arguments before
|
|||
|
input arguments. This notation is based on an analogy with the
|
|||
|
assignment operator. (The BSD MP compatibility functions disobey this
|
|||
|
rule, having the output argument(s) last.)
|
|||
|
|
|||
|
MP allows you to use the same variable for both input and output in
|
|||
|
the same expression. For example, the main function for integer
|
|||
|
multiplication, `mpz_mul', can be used like this: `mpz_mul (x, x, x)'.
|
|||
|
This computes the square of X and puts the result back in X.
|
|||
|
|
|||
|
Before you can assign to an MP variable, you need to initialize it
|
|||
|
by calling one of the special initialization functions. When you're
|
|||
|
done with a variable, you need to clear it out, using one of the
|
|||
|
functions for that purpose. Which function to use depends on the type
|
|||
|
of variable. See the chapters on integer functions, rational number
|
|||
|
functions, and floating-point functions for details.
|
|||
|
|
|||
|
A variable should only be initialized once, or at least cleared out
|
|||
|
between each initialization. After a variable has been initialized, it
|
|||
|
may be assigned to any number of times.
|
|||
|
|
|||
|
For efficiency reasons, avoid to initialize and clear out a variable
|
|||
|
in loops. Instead, initialize it before entering the loop, and clear
|
|||
|
it out after the loop has exited.
|
|||
|
|
|||
|
You don't need to be concerned about allocating additional space for
|
|||
|
MP variables. All functions in MP automatically allocate additional
|
|||
|
space when a variable does not already have enough space. They do not,
|
|||
|
however, reduce the space when a smaller number is stored in the
|
|||
|
object. Most of the time, this policy is best, since it avoids
|
|||
|
frequent re-allocation.
|
|||
|
|
|||
|
Useful Macros and Constants
|
|||
|
===========================
|
|||
|
|
|||
|
- Global Constant: const int mp_bits_per_limb
|
|||
|
The number of bits per limb.
|
|||
|
|
|||
|
- Macro: __GNU_MP_VERSION
|
|||
|
- Macro: __GNU_MP_VERSION_MINOR
|
|||
|
The major and minor MP version, respectively, as integers.
|
|||
|
|
|||
|
Compatibility with Version 1.x
|
|||
|
==============================
|
|||
|
|
|||
|
This version of MP is upward compatible with previous versions of
|
|||
|
MP, with a few exceptions.
|
|||
|
|
|||
|
1. Integer division functions round the result differently. The old
|
|||
|
functions (`mpz_div', `mpz_divmod', `mpz_mdiv', `mpz_mdivmod',
|
|||
|
etc) now all use floor rounding (i.e., they round the quotient to
|
|||
|
-infinity). There are a lot of new functions for integer
|
|||
|
division, giving the user better control over the rounding.
|
|||
|
|
|||
|
2. The function `mpz_mod' now compute the true *mod* function.
|
|||
|
|
|||
|
3. The functions `mpz_powm' and `mpz_powm_ui' now use *mod* for
|
|||
|
reduction.
|
|||
|
|
|||
|
4. The assignment functions for rational numbers do no longer
|
|||
|
canonicalize their results. In the case a non-canonical result
|
|||
|
could arise from an assignment, the user need to insert an
|
|||
|
explicit call to `mpq_canonicalize'. This change was made for
|
|||
|
efficiency.
|
|||
|
|
|||
|
5. Output generated by `mpz_out_raw' in this release cannot be read
|
|||
|
by `mpz_inp_raw' in previous releases. This change was made for
|
|||
|
making the file format truly portable between machines with
|
|||
|
different word sizes.
|
|||
|
|
|||
|
6. Several `mpn' functions have changed. But they were intentionally
|
|||
|
undocumented in previous releases.
|
|||
|
|
|||
|
7. The functions `mpz_cmp_ui', `mpz_cmp_si', and `mpq_cmp_ui' are now
|
|||
|
implementated as macros, and thereby sometimes evaluate their
|
|||
|
arguments multiple times.
|
|||
|
|
|||
|
8. The functions `mpz_pow_ui' and `mpz_ui_pow_ui' now yield 1 for
|
|||
|
0^0. (In version 1, they yielded 0.)
|
|||
|
|
|||
|
|
|||
|
Getting the Latest Version of MP
|
|||
|
================================
|
|||
|
|
|||
|
The latest version of the MP library is available by anonymous ftp
|
|||
|
from from `prep.ai.mit.edu'. The file name is
|
|||
|
`/pub/gnu/gmp-M.N.tar.gz'. Many sites around the world mirror `prep';
|
|||
|
please use a mirror site near you.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Reporting Bugs, Next: Integer Functions, Prev: MP Basics, Up: Top
|
|||
|
|
|||
|
Reporting Bugs
|
|||
|
**************
|
|||
|
|
|||
|
If you think you have found a bug in the MP library, please
|
|||
|
investigate it and report it. We have made this library available to
|
|||
|
you, and it is not to ask too much from you, to ask you to report the
|
|||
|
bugs that you find.
|
|||
|
|
|||
|
There are a few things you should think about when you put your bug
|
|||
|
report together.
|
|||
|
|
|||
|
You have to send us a test case that makes it possible for us to
|
|||
|
reproduce the bug. Include instructions on how to run the test case.
|
|||
|
|
|||
|
You also have to explain what is wrong; if you get a crash, or if
|
|||
|
the results printed are incorrect and in that case, in what way.
|
|||
|
|
|||
|
It is not uncommon that an observed problem is actually due to a bug
|
|||
|
in the compiler used when building MP; the MP code tends to explore
|
|||
|
interesting corners in compilers. Therefore, please include compiler
|
|||
|
version information in your bug report. This can be extracted using
|
|||
|
`what `which cc`', or, if you're using gcc, `gcc -v'. Also, include
|
|||
|
the output from `uname -a'.
|
|||
|
|
|||
|
If your bug report is good, we will do our best to help you to get a
|
|||
|
corrected version of the library; if the bug report is poor, we won't
|
|||
|
do anything about it (aside of chiding you to send better bug reports).
|
|||
|
|
|||
|
Send your bug report to: `bug-gmp@prep.ai.mit.edu'.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Integer Functions, Next: Rational Number Functions, Prev: Reporting Bugs, Up: Top
|
|||
|
|
|||
|
Integer Functions
|
|||
|
*****************
|
|||
|
|
|||
|
This chapter describes the MP functions for performing integer
|
|||
|
arithmetic. These functions start with the prefix `mpz_'.
|
|||
|
|
|||
|
Arbitrary precision integers are stored in objects of type `mpz_t'.
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* Initializing Integers::
|
|||
|
* Assigning Integers::
|
|||
|
* Simultaneous Integer Init & Assign::
|
|||
|
* Converting Integers::
|
|||
|
* Integer Arithmetic::
|
|||
|
* Comparison Functions::
|
|||
|
* Integer Logic and Bit Fiddling::
|
|||
|
* I/O of Integers::
|
|||
|
* Miscellaneous Integer Functions::
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Initializing Integers, Next: Assigning Integers, Up: Integer Functions
|
|||
|
|
|||
|
Initialization and Assignment Functions
|
|||
|
=======================================
|
|||
|
|
|||
|
The functions for integer arithmetic assume that all integer objects
|
|||
|
are initialized. You do that by calling the function `mpz_init'.
|
|||
|
|
|||
|
- Function: void mpz_init (mpz_t INTEGER)
|
|||
|
Initialize INTEGER with limb space and set the initial numeric
|
|||
|
value to 0. Each variable should normally only be initialized
|
|||
|
once, or at least cleared out (using `mpz_clear') between each
|
|||
|
initialization.
|
|||
|
|
|||
|
Here is an example of using `mpz_init':
|
|||
|
|
|||
|
{
|
|||
|
mpz_t integ;
|
|||
|
mpz_init (integ);
|
|||
|
...
|
|||
|
mpz_add (integ, ...);
|
|||
|
...
|
|||
|
mpz_sub (integ, ...);
|
|||
|
|
|||
|
/* Unless the program is about to exit, do ... */
|
|||
|
mpz_clear (integ);
|
|||
|
}
|
|||
|
|
|||
|
As you can see, you can store new values any number of times, once an
|
|||
|
object is initialized.
|
|||
|
|
|||
|
- Function: void mpz_clear (mpz_t INTEGER)
|
|||
|
Free the limb space occupied by INTEGER. Make sure to call this
|
|||
|
function for all `mpz_t' variables when you are done with them.
|
|||
|
|
|||
|
- Function: void * _mpz_realloc (mpz_t INTEGER, mp_size_t NEW_ALLOC)
|
|||
|
Change the limb space allocation to NEW_ALLOC limbs. This
|
|||
|
function is not normally called from user code, but it can be used
|
|||
|
to give memory back to the heap, or to increase the space of a
|
|||
|
variable to avoid repeated automatic re-allocation.
|
|||
|
|
|||
|
- Function: void mpz_array_init (mpz_t INTEGER_ARRAY[], size_t
|
|||
|
ARRAY_SIZE, mp_size_t FIXED_NUM_BITS)
|
|||
|
Allocate *fixed* limb space for all ARRAY_SIZE integers in
|
|||
|
INTEGER_ARRAY. The fixed allocation for each integer in the array
|
|||
|
is enough to store FIXED_NUM_BITS. If the fixed space will be
|
|||
|
insufficient for storing the result of a subsequent calculation,
|
|||
|
the result is unpredictable.
|
|||
|
|
|||
|
This function is useful for decreasing the working set for some
|
|||
|
algorithms that use large integer arrays.
|
|||
|
|
|||
|
There is no way to de-allocate the storage allocated by this
|
|||
|
function. Don't call `mpz_clear'!
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Assigning Integers, Next: Simultaneous Integer Init & Assign, Prev: Initializing Integers, Up: Integer Functions
|
|||
|
|
|||
|
Assignment Functions
|
|||
|
--------------------
|
|||
|
|
|||
|
These functions assign new values to already initialized integers
|
|||
|
(*note Initializing Integers::.).
|
|||
|
|
|||
|
- Function: void mpz_set (mpz_t ROP, mpz_t OP)
|
|||
|
- Function: void mpz_set_ui (mpz_t ROP, unsigned long int OP)
|
|||
|
- Function: void mpz_set_si (mpz_t ROP, signed long int OP)
|
|||
|
- Function: void mpz_set_d (mpz_t ROP, double OP)
|
|||
|
- Function: void mpz_set_q (mpz_t ROP, mpq_t OP)
|
|||
|
- Function: void mpz_set_f (mpz_t ROP, mpf_t OP)
|
|||
|
Set the value of ROP from OP.
|
|||
|
|
|||
|
- Function: int mpz_set_str (mpz_t ROP, char *STR, int BASE)
|
|||
|
Set the value of ROP from STR, a '\0'-terminated C string in base
|
|||
|
BASE. White space is allowed in the string, and is simply
|
|||
|
ignored. The base may vary from 2 to 36. If BASE is 0, the
|
|||
|
actual base is determined from the leading characters: if the
|
|||
|
first two characters are `0x' or `0X', hexadecimal is assumed,
|
|||
|
otherwise if the first character is `0', octal is assumed,
|
|||
|
otherwise decimal is assumed.
|
|||
|
|
|||
|
This function returns 0 if the entire string up to the '\0' is a
|
|||
|
valid number in base BASE. Otherwise it returns -1.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Simultaneous Integer Init & Assign, Next: Converting Integers, Prev: Assigning Integers, Up: Integer Functions
|
|||
|
|
|||
|
Combined Initialization and Assignment Functions
|
|||
|
------------------------------------------------
|
|||
|
|
|||
|
For convenience, MP provides a parallel series of initialize-and-set
|
|||
|
functions which initialize the output and then store the value there.
|
|||
|
These functions' names have the form `mpz_init_set...'
|
|||
|
|
|||
|
Here is an example of using one:
|
|||
|
|
|||
|
{
|
|||
|
mpz_t pie;
|
|||
|
mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10);
|
|||
|
...
|
|||
|
mpz_sub (pie, ...);
|
|||
|
...
|
|||
|
mpz_clear (pie);
|
|||
|
}
|
|||
|
|
|||
|
Once the integer has been initialized by any of the `mpz_init_set...'
|
|||
|
functions, it can be used as the source or destination operand for the
|
|||
|
ordinary integer functions. Don't use an initialize-and-set function
|
|||
|
on a variable already initialized!
|
|||
|
|
|||
|
- Function: void mpz_init_set (mpz_t ROP, mpz_t OP)
|
|||
|
- Function: void mpz_init_set_ui (mpz_t ROP, unsigned long int OP)
|
|||
|
- Function: void mpz_init_set_si (mpz_t ROP, signed long int OP)
|
|||
|
- Function: void mpz_init_set_d (mpz_t ROP, double OP)
|
|||
|
Initialize ROP with limb space and set the initial numeric value
|
|||
|
from OP.
|
|||
|
|
|||
|
- Function: int mpz_init_set_str (mpz_t ROP, char *STR, int BASE)
|
|||
|
Initialize ROP and set its value like `mpz_set_str' (see its
|
|||
|
documentation above for details).
|
|||
|
|
|||
|
If the string is a correct base BASE number, the function returns
|
|||
|
0; if an error occurs it returns -1. ROP is initialized even if
|
|||
|
an error occurs. (I.e., you have to call `mpz_clear' for it.)
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Converting Integers, Next: Integer Arithmetic, Prev: Simultaneous Integer Init & Assign, Up: Integer Functions
|
|||
|
|
|||
|
Conversion Functions
|
|||
|
====================
|
|||
|
|
|||
|
This section describes functions for converting arbitrary precision
|
|||
|
integers to standard C types. Functions for converting *to* arbitrary
|
|||
|
precision integers are described in *Note Assigning Integers:: and
|
|||
|
*Note I/O of Integers::.
|
|||
|
|
|||
|
- Function: unsigned long int mpz_get_ui (mpz_t OP)
|
|||
|
Return the least significant part from OP. This function combined
|
|||
|
with
|
|||
|
`mpz_tdiv_q_2exp(..., OP, CHAR_BIT*sizeof(unsigned long int))' can
|
|||
|
be used to extract the limbs of an integer.
|
|||
|
|
|||
|
- Function: signed long int mpz_get_si (mpz_t OP)
|
|||
|
If OP fits into a `signed long int' return the value of OP.
|
|||
|
Otherwise return the least significant part of OP, with the same
|
|||
|
sign as OP.
|
|||
|
|
|||
|
If OP is too large to fit in a `signed long int', the returned
|
|||
|
result is probably not very useful.
|
|||
|
|
|||
|
- Function: double mpz_get_d (mpz_t OP)
|
|||
|
Convert OP to a double.
|
|||
|
|
|||
|
- Function: char * mpz_get_str (char *STR, int BASE, mpz_t OP)
|
|||
|
Convert OP to a string of digits in base BASE. The base may vary
|
|||
|
from 2 to 36.
|
|||
|
|
|||
|
If STR is NULL, space for the result string is allocated using the
|
|||
|
default allocation function, and a pointer to the string is
|
|||
|
returned.
|
|||
|
|
|||
|
If STR is not 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 STR, use `mpz_sizeinbase (OP, BASE) + 2'. The two
|
|||
|
extra bytes are for a possible minus sign, and for the terminating
|
|||
|
null character.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Integer Arithmetic, Next: Comparison Functions, Prev: Converting Integers, Up: Integer Functions
|
|||
|
|
|||
|
Arithmetic Functions
|
|||
|
====================
|
|||
|
|
|||
|
- Function: void mpz_add (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
- Function: void mpz_add_ui (mpz_t ROP, mpz_t OP1, unsigned long int
|
|||
|
OP2)
|
|||
|
Set ROP to OP1 + OP2.
|
|||
|
|
|||
|
- Function: void mpz_sub (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
- Function: void mpz_sub_ui (mpz_t ROP, mpz_t OP1, unsigned long int
|
|||
|
OP2)
|
|||
|
Set ROP to OP1 - OP2.
|
|||
|
|
|||
|
- Function: void mpz_mul (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
- Function: void mpz_mul_ui (mpz_t ROP, mpz_t OP1, unsigned long int
|
|||
|
OP2)
|
|||
|
Set ROP to OP1 times OP2.
|
|||
|
|
|||
|
- Function: void mpz_mul_2exp (mpz_t ROP, mpz_t OP1, unsigned long int
|
|||
|
OP2)
|
|||
|
Set ROP to OP1 times 2 raised to OP2. This operation can also be
|
|||
|
defined as a left shift, OP2 steps.
|
|||
|
|
|||
|
- Function: void mpz_neg (mpz_t ROP, mpz_t OP)
|
|||
|
Set ROP to -OP.
|
|||
|
|
|||
|
- Function: void mpz_abs (mpz_t ROP, mpz_t OP)
|
|||
|
Set ROP to the absolute value of OP.
|
|||
|
|
|||
|
- Function: void mpz_fac_ui (mpz_t ROP, unsigned long int OP)
|
|||
|
Set ROP to OP!, the factorial of OP.
|
|||
|
|
|||
|
Division functions
|
|||
|
------------------
|
|||
|
|
|||
|
Division is undefined if the divisor is zero, and passing a zero
|
|||
|
divisor to the divide or modulo functions, as well passing a zero mod
|
|||
|
argument to the `mpz_powm' and `mpz_powm_ui' functions, will make these
|
|||
|
functions intentionally divide by zero. This gives the user the
|
|||
|
possibility to handle arithmetic exceptions in these functions in the
|
|||
|
same manner as other arithmetic exceptions.
|
|||
|
|
|||
|
There are three main groups of division functions:
|
|||
|
* Functions that truncate the quotient towards 0. The names of these
|
|||
|
functions start with `mpz_tdiv'. The `t' in the name is short for
|
|||
|
`truncate'.
|
|||
|
|
|||
|
* Functions that round the quotient towards -infinity. The names of
|
|||
|
these routines start with `mpz_fdiv'. The `f' in the name is
|
|||
|
short for `floor'.
|
|||
|
|
|||
|
* Functions that round the quotient towards +infinity. The names of
|
|||
|
these routines start with `mpz_cdiv'. The `c' in the name is
|
|||
|
short for `ceil'.
|
|||
|
|
|||
|
For each rounding mode, there are a couple of variants. Here `q'
|
|||
|
means that the quotient is computed, while `r' means that the remainder
|
|||
|
is computed. Functions that compute both the quotient and remainder
|
|||
|
have `qr' in the name.
|
|||
|
|
|||
|
- Function: void mpz_tdiv_q (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
- Function: void mpz_tdiv_q_ui (mpz_t ROP, mpz_t OP1, unsigned long
|
|||
|
int OP2)
|
|||
|
Set ROP to [OP1/OP2]. The quotient is truncated towards 0.
|
|||
|
|
|||
|
- Function: void mpz_tdiv_r (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
- Function: void mpz_tdiv_r_ui (mpz_t ROP, mpz_t OP1, unsigned long
|
|||
|
int OP2)
|
|||
|
Set ROP to (OP1 - [OP1/OP2] * OP2). Unless the remainder is zero,
|
|||
|
it has the same sign as the dividend.
|
|||
|
|
|||
|
- Function: void mpz_tdiv_qr (mpz_t ROP1, mpz_t ROP2, mpz_t OP1, mpz_t
|
|||
|
OP2)
|
|||
|
- Function: void mpz_tdiv_qr_ui (mpz_t ROP1, mpz_t ROP2, mpz_t OP1,
|
|||
|
unsigned long int OP2)
|
|||
|
Divide OP1 by OP2 and put the quotient in ROP1 and the remainder
|
|||
|
in ROP2. The quotient is rounded towards 0. Unless the remainder
|
|||
|
is zero, it has the same sign as the dividend.
|
|||
|
|
|||
|
If ROP1 and ROP2 are the same variable, the results are undefined.
|
|||
|
|
|||
|
- Function: void mpz_fdiv_q (mpz_t ROP1, mpz_t OP1, mpz_t OP2)
|
|||
|
- Function: void mpz_fdiv_q_ui (mpz_t ROP, mpz_t OP1, unsigned long
|
|||
|
int OP2)
|
|||
|
Set ROP to OP1/OP2. The quotient is rounded towards -infinity.
|
|||
|
|
|||
|
- Function: void mpz_fdiv_r (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
- Function: unsigned long int mpz_fdiv_r_ui (mpz_t ROP, mpz_t OP1,
|
|||
|
unsigned long int OP2)
|
|||
|
Divide OP1 by OP2 and put the remainder in ROP. Unless the
|
|||
|
remainder is zero, it has the same sign as the divisor.
|
|||
|
|
|||
|
For `mpz_fdiv_r_ui' the remainder is small enough to fit in an
|
|||
|
`unsigned long int', and is therefore returned.
|
|||
|
|
|||
|
- Function: void mpz_fdiv_qr (mpz_t ROP1, mpz_t ROP2, mpz_t OP1, mpz_t
|
|||
|
OP2)
|
|||
|
- Function: unsigned long int mpz_fdiv_qr_ui (mpz_t ROP1, mpz_t ROP2,
|
|||
|
mpz_t OP1, unsigned long int OP2)
|
|||
|
Divide OP1 by OP2 and put the quotient in ROP1 and the remainder
|
|||
|
in ROP2. The quotient is rounded towards -infinity. Unless the
|
|||
|
remainder is zero, it has the same sign as the divisor.
|
|||
|
|
|||
|
For `mpz_fdiv_qr_ui' the remainder is small enough to fit in an
|
|||
|
`unsigned long int', and is therefore returned.
|
|||
|
|
|||
|
If ROP1 and ROP2 are the same variable, the results are undefined.
|
|||
|
|
|||
|
- Function: unsigned long int mpz_fdiv_ui (mpz_t OP1, unsigned long
|
|||
|
int OP2)
|
|||
|
This function is similar to `mpz_fdiv_r_ui', but the remainder is
|
|||
|
only returned; it is not stored anywhere.
|
|||
|
|
|||
|
- Function: void mpz_cdiv_q (mpz_t ROP1, mpz_t OP1, mpz_t OP2)
|
|||
|
- Function: void mpz_cdiv_q_ui (mpz_t ROP, mpz_t OP1, unsigned long
|
|||
|
int OP2)
|
|||
|
Set ROP to OP1/OP2. The quotient is rounded towards +infinity.
|
|||
|
|
|||
|
- Function: void mpz_cdiv_r (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
- Function: unsigned long int mpz_cdiv_r_ui (mpz_t ROP, mpz_t OP1,
|
|||
|
unsigned long int OP2)
|
|||
|
Divide OP1 by OP2 and put the remainder in ROP. Unless the
|
|||
|
remainder is zero, it has the opposite sign as the divisor.
|
|||
|
|
|||
|
For `mpz_cdiv_r_ui' the negated remainder is small enough to fit
|
|||
|
in an `unsigned long int', and it is therefore returned.
|
|||
|
|
|||
|
- Function: void mpz_cdiv_qr (mpz_t ROP1, mpz_t ROP2, mpz_t OP1, mpz_t
|
|||
|
OP2)
|
|||
|
- Function: unsigned long int mpz_cdiv_qr_ui (mpz_t ROP1, mpz_t ROP2,
|
|||
|
mpz_t OP1, unsigned long int OP2)
|
|||
|
Divide OP1 by OP2 and put the quotient in ROP1 and the remainder
|
|||
|
in ROP2. The quotient is rounded towards +infinity. Unless the
|
|||
|
remainder is zero, it has the opposite sign as the divisor.
|
|||
|
|
|||
|
For `mpz_cdiv_qr_ui' the negated remainder is small enough to fit
|
|||
|
in an `unsigned long int', and it is therefore returned.
|
|||
|
|
|||
|
If ROP1 and ROP2 are the same variable, the results are undefined.
|
|||
|
|
|||
|
- Function: unsigned long int mpz_cdiv_ui (mpz_t OP1, unsigned long
|
|||
|
int OP2)
|
|||
|
Return the negated remainder, similar to `mpz_cdiv_r_ui'. (The
|
|||
|
difference is that this function doesn't store the remainder
|
|||
|
anywhere.)
|
|||
|
|
|||
|
- Function: void mpz_mod (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
- Function: unsigned long int mpz_mod_ui (mpz_t ROP, mpz_t OP1,
|
|||
|
unsigned long int OP2)
|
|||
|
Set ROP to OP1 `mod' OP2. The sign of the divisor is ignored, and
|
|||
|
the result is always non-negative.
|
|||
|
|
|||
|
For `mpz_mod_ui' the remainder is small enough to fit in an
|
|||
|
`unsigned long int', and is therefore returned.
|
|||
|
|
|||
|
- Function: void mpz_divexact (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
Set ROP to OP1/OP2. This function produces correct results only
|
|||
|
when it is known in advance that OP2 divides OP1.
|
|||
|
|
|||
|
Since mpz_divexact is much faster than any of the other routines
|
|||
|
that produce the quotient (*note References::. Jebelean), it is
|
|||
|
the best choice for instances in which exact division is known to
|
|||
|
occur, such as reducing a rational to lowest terms.
|
|||
|
|
|||
|
- Function: void mpz_tdiv_q_2exp (mpz_t ROP, mpz_t OP1, unsigned long
|
|||
|
int OP2)
|
|||
|
Set ROP to OP1 divided by 2 raised to OP2. The quotient is
|
|||
|
rounded towards 0.
|
|||
|
|
|||
|
- Function: void mpz_tdiv_r_2exp (mpz_t ROP, mpz_t OP1, unsigned long
|
|||
|
int OP2)
|
|||
|
Divide OP1 by (2 raised to OP2) and put the remainder in ROP.
|
|||
|
Unless it is zero, ROP will have the same sign as OP1.
|
|||
|
|
|||
|
- Function: void mpz_fdiv_q_2exp (mpz_t ROP, mpz_t OP1, unsigned long
|
|||
|
int OP2)
|
|||
|
Set ROP to OP1 divided by 2 raised to OP2. The quotient is
|
|||
|
rounded towards -infinity.
|
|||
|
|
|||
|
- Function: void mpz_fdiv_r_2exp (mpz_t ROP, mpz_t OP1, unsigned long
|
|||
|
int OP2)
|
|||
|
Divide OP1 by (2 raised to OP2) and put the remainder in ROP. The
|
|||
|
sign of ROP will always be positive.
|
|||
|
|
|||
|
This operation can also be defined as masking of the OP2 least
|
|||
|
significant bits.
|
|||
|
|
|||
|
Exponentialization Functions
|
|||
|
----------------------------
|
|||
|
|
|||
|
- Function: void mpz_powm (mpz_t ROP, mpz_t BASE, mpz_t EXP, mpz_t MOD)
|
|||
|
- Function: void mpz_powm_ui (mpz_t ROP, mpz_t BASE, unsigned long int
|
|||
|
EXP, mpz_t MOD)
|
|||
|
Set ROP to (BASE raised to EXP) `mod' MOD. If EXP is negative,
|
|||
|
the result is undefined.
|
|||
|
|
|||
|
- Function: void mpz_pow_ui (mpz_t ROP, mpz_t BASE, unsigned long int
|
|||
|
EXP)
|
|||
|
- Function: void mpz_ui_pow_ui (mpz_t ROP, unsigned long int BASE,
|
|||
|
unsigned long int EXP)
|
|||
|
Set ROP to BASE raised to EXP. The case of 0^0 yields 1.
|
|||
|
|
|||
|
Square Root Functions
|
|||
|
---------------------
|
|||
|
|
|||
|
- Function: void mpz_sqrt (mpz_t ROP, mpz_t OP)
|
|||
|
Set ROP to the truncated integer part of the square root of OP.
|
|||
|
|
|||
|
- Function: void mpz_sqrtrem (mpz_t ROP1, mpz_t ROP2, mpz_t OP)
|
|||
|
Set ROP1 to the truncated integer part of the square root of OP,
|
|||
|
like `mpz_sqrt'. Set ROP2 to OP-ROP1*ROP1, (i.e., zero if OP is a
|
|||
|
perfect square).
|
|||
|
|
|||
|
If ROP1 and ROP2 are the same variable, the results are undefined.
|
|||
|
|
|||
|
- Function: int mpz_perfect_square_p (mpz_t OP)
|
|||
|
Return non-zero if OP is a perfect square, i.e., if the square
|
|||
|
root of OP is an integer. Return zero otherwise.
|
|||
|
|
|||
|
Number Theoretic Functions
|
|||
|
--------------------------
|
|||
|
|
|||
|
- Function: int mpz_probab_prime_p (mpz_t OP, int REPS)
|
|||
|
If this function returns 0, OP is definitely not prime. If it
|
|||
|
returns 1, then OP is `probably' prime. The probability of a
|
|||
|
false positive is (1/4)**REPS. A reasonable value of reps is 25.
|
|||
|
|
|||
|
An implementation of the probabilistic primality test found in
|
|||
|
Seminumerical Algorithms (*note References::. Knuth).
|
|||
|
|
|||
|
- Function: void mpz_gcd (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
Set ROP to the greatest common divisor of OP1 and OP2.
|
|||
|
|
|||
|
- Function: unsigned long int mpz_gcd_ui (mpz_t ROP, mpz_t OP1,
|
|||
|
unsigned long int OP2)
|
|||
|
Compute the greatest common divisor of OP1 and OP2. If ROP is not
|
|||
|
NULL, store the result there.
|
|||
|
|
|||
|
If the result is small enough to fit in an `unsigned long int', it
|
|||
|
is returned. If the result does not fit, 0 is returned, and the
|
|||
|
result is equal to the argument OP1. Note that the result will
|
|||
|
always fit if OP2 is non-zero.
|
|||
|
|
|||
|
- Function: void mpz_gcdext (mpz_t G, mpz_t S, mpz_t T, mpz_t A, mpz_t
|
|||
|
B)
|
|||
|
Compute G, S, and T, such that AS + BT = G = `gcd' (A, B). If T is
|
|||
|
NULL, that argument is not computed.
|
|||
|
|
|||
|
- Function: int mpz_invert (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
Compute the inverse of OP1 modulo OP2 and put the result in ROP.
|
|||
|
Return non-zero if an inverse exist, zero otherwise. When the
|
|||
|
function returns zero, do not assume anything about the value in
|
|||
|
ROP.
|
|||
|
|
|||
|
- Function: int mpz_jacobi (mpz_t OP1, mpz_t OP2)
|
|||
|
- Function: int mpz_legendre (mpz_t OP1, mpz_t OP2)
|
|||
|
Compute the Jacobi and Legendre symbols, respectively.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Comparison Functions, Next: Integer Logic and Bit Fiddling, Prev: Integer Arithmetic, Up: Integer Functions
|
|||
|
|
|||
|
Comparison Functions
|
|||
|
====================
|
|||
|
|
|||
|
- Function: int mpz_cmp (mpz_t OP1, mpz_t OP2)
|
|||
|
Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
|
|||
|
if OP1 = OP2, and a negative value if OP1 < OP2.
|
|||
|
|
|||
|
- Macro: int mpz_cmp_ui (mpz_t OP1, unsigned long int OP2)
|
|||
|
- Macro: int mpz_cmp_si (mpz_t OP1, signed long int OP2)
|
|||
|
Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
|
|||
|
if OP1 = OP2, and a negative value if OP1 < OP2.
|
|||
|
|
|||
|
These functions are actually implemented as macros. They evaluate
|
|||
|
their arguments multiple times.
|
|||
|
|
|||
|
- Macro: int mpz_sgn (mpz_t OP)
|
|||
|
Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.
|
|||
|
|
|||
|
This function is actually implemented as a macro. It evaluates its
|
|||
|
arguments multiple times.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Integer Logic and Bit Fiddling, Next: I/O of Integers, Prev: Comparison Functions, Up: Integer Functions
|
|||
|
|
|||
|
Logical and Bit Manipulation Functions
|
|||
|
======================================
|
|||
|
|
|||
|
These functions behave as if two's complement arithmetic were used
|
|||
|
(although sign-magnitude is used by the actual implementation).
|
|||
|
|
|||
|
- Function: void mpz_and (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
Set ROP to OP1 logical-and OP2.
|
|||
|
|
|||
|
- Function: void mpz_ior (mpz_t ROP, mpz_t OP1, mpz_t OP2)
|
|||
|
Set ROP to OP1 inclusive-or OP2.
|
|||
|
|
|||
|
- Function: void mpz_com (mpz_t ROP, mpz_t OP)
|
|||
|
Set ROP to the one's complement of OP.
|
|||
|
|
|||
|
- Function: unsigned long int mpz_popcount (mpz_t OP)
|
|||
|
For non-negative numbers, return the population count of OP. For
|
|||
|
negative numbers, return the largest possible value (MAX_ULONG).
|
|||
|
|
|||
|
- Function: unsigned long int mpz_hamdist (mpz_t OP1, mpz_t OP2)
|
|||
|
If OP1 and OP2 are both non-negative, return the hamming distance
|
|||
|
between the two operands. Otherwise, return the largest possible
|
|||
|
value (MAX_ULONG).
|
|||
|
|
|||
|
It is possible to extend this function to return a useful value
|
|||
|
when the operands are both negative, but the current
|
|||
|
implementation returns MAX_ULONG in this case. *Do not depend on
|
|||
|
this behavior, since it will change in future versions of the
|
|||
|
library.*
|
|||
|
|
|||
|
- Function: unsigned long int mpz_scan0 (mpz_t OP, unsigned long int
|
|||
|
STARTING_BIT)
|
|||
|
Scan OP, starting with bit STARTING_BIT, towards more significant
|
|||
|
bits, until the first clear bit is found. Return the index of the
|
|||
|
found bit.
|
|||
|
|
|||
|
- Function: unsigned long int mpz_scan1 (mpz_t OP, unsigned long int
|
|||
|
STARTING_BIT)
|
|||
|
Scan OP, starting with bit STARTING_BIT, towards more significant
|
|||
|
bits, until the first set bit is found. Return the index of the
|
|||
|
found bit.
|
|||
|
|
|||
|
- Function: void mpz_setbit (mpz_t ROP, unsigned long int BIT_INDEX)
|
|||
|
Set bit BIT_INDEX in OP1.
|
|||
|
|
|||
|
- Function: void mpz_clrbit (mpz_t ROP, unsigned long int BIT_INDEX)
|
|||
|
Clear bit BIT_INDEX in OP1.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: I/O of Integers, Next: Miscellaneous Integer Functions, Prev: Integer Logic and Bit Fiddling, Up: Integer Functions
|
|||
|
|
|||
|
Input and Output Functions
|
|||
|
==========================
|
|||
|
|
|||
|
Functions that perform input from a stdio stream, and functions that
|
|||
|
output to a stdio stream. Passing a NULL pointer for a STREAM argument
|
|||
|
to any of these functions will make them read from `stdin' and write to
|
|||
|
`stdout', respectively.
|
|||
|
|
|||
|
When using any of these functions, it is a good idea to include
|
|||
|
`stdio.h' before `gmp.h', since that will allow `gmp.h' to define
|
|||
|
prototypes for these functions.
|
|||
|
|
|||
|
- Function: size_t mpz_out_str (FILE *STREAM, int BASE, mpz_t OP)
|
|||
|
Output OP on stdio stream STREAM, as a string of digits in base
|
|||
|
BASE. The base may vary from 2 to 36.
|
|||
|
|
|||
|
Return the number of bytes written, or if an error occurred,
|
|||
|
return 0.
|
|||
|
|
|||
|
- Function: size_t mpz_inp_str (mpz_t ROP, FILE *STREAM, int BASE)
|
|||
|
Input a possibly white-space preceded string in base BASE from
|
|||
|
stdio stream STREAM, and put the read integer in ROP. The base
|
|||
|
may vary from 2 to 36. If BASE is 0, the actual base is
|
|||
|
determined from the leading characters: if the first two
|
|||
|
characters are `0x' or `0X', hexadecimal is assumed, otherwise if
|
|||
|
the first character is `0', octal is assumed, otherwise decimal is
|
|||
|
assumed.
|
|||
|
|
|||
|
Return the number of bytes read, or if an error occurred, return 0.
|
|||
|
|
|||
|
- Function: size_t mpz_out_raw (FILE *STREAM, mpz_t OP)
|
|||
|
Output OP on stdio stream STREAM, in raw binary format. The
|
|||
|
integer is written in a portable format, with 4 bytes of size
|
|||
|
information, and that many bytes of limbs. Both the size and the
|
|||
|
limbs are written in decreasing significance order (i.e., in
|
|||
|
big-endian).
|
|||
|
|
|||
|
The output can be read with `mpz_inp_raw'.
|
|||
|
|
|||
|
Return the number of bytes written, or if an error occurred,
|
|||
|
return 0.
|
|||
|
|
|||
|
The output of this can not be read by `mpz_inp_raw' from GMP 1,
|
|||
|
because of changes necessary for compatibility between 32-bit and
|
|||
|
64-bit machines.
|
|||
|
|
|||
|
- Function: size_t mpz_inp_raw (mpz_t ROP, FILE *STREAM)
|
|||
|
Input from stdio stream STREAM in the format written by
|
|||
|
`mpz_out_raw', and put the result in ROP. Return the number of
|
|||
|
bytes read, or if an error occurred, return 0.
|
|||
|
|
|||
|
This routine can read the output from `mpz_out_raw' also from GMP
|
|||
|
1, in spite of changes necessary for compatibility between 32-bit
|
|||
|
and 64-bit machines.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Miscellaneous Integer Functions, Prev: I/O of Integers, Up: Integer Functions
|
|||
|
|
|||
|
Miscellaneous Functions
|
|||
|
=======================
|
|||
|
|
|||
|
- Function: void mpz_random (mpz_t ROP, mp_size_t MAX_SIZE)
|
|||
|
Generate a random integer of at most MAX_SIZE limbs. The generated
|
|||
|
random number doesn't satisfy any particular requirements of
|
|||
|
randomness. Negative random numbers are generated when MAX_SIZE
|
|||
|
is negative.
|
|||
|
|
|||
|
- Function: void mpz_random2 (mpz_t ROP, mp_size_t MAX_SIZE)
|
|||
|
Generate a random integer of at most MAX_SIZE limbs, 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.
|
|||
|
Negative random numbers are generated when MAX_SIZE is negative.
|
|||
|
|
|||
|
- Function: size_t mpz_size (mpz_t OP)
|
|||
|
Return the size of OP measured in number of limbs. If OP is zero,
|
|||
|
the returned value will be zero.
|
|||
|
|
|||
|
*This function is obsolete. It will disappear from future MP
|
|||
|
releases.*
|
|||
|
|
|||
|
- Function: size_t mpz_sizeinbase (mpz_t OP, int BASE)
|
|||
|
Return the size of OP measured in number of digits in base BASE.
|
|||
|
The base may vary from 2 to 36. The returned value will be exact
|
|||
|
or 1 too big. If BASE is a power of 2, the returned value will
|
|||
|
always be exact.
|
|||
|
|
|||
|
This function is useful in order to allocate the right amount of
|
|||
|
space before converting OP to a string. The right amount of
|
|||
|
allocation is normally two more than the value returned by
|
|||
|
`mpz_sizeinbase' (one extra for a minus sign and one for the
|
|||
|
terminating '\0').
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Rational Number Functions, Next: Floating-point Functions, Prev: Integer Functions, Up: Top
|
|||
|
|
|||
|
Rational Number Functions
|
|||
|
*************************
|
|||
|
|
|||
|
This chapter describes the MP functions for performing arithmetic on
|
|||
|
rational numbers. These functions start with the prefix `mpq_'.
|
|||
|
|
|||
|
Rational numbers are stored in objects of type `mpq_t'.
|
|||
|
|
|||
|
All rational arithmetic functions assume operands have a canonical
|
|||
|
form, and canonicalize their result. The canonical from means that the
|
|||
|
denominator and the numerator have no common factors, and that the
|
|||
|
denominator is positive. Zero has the unique representation 0/1.
|
|||
|
|
|||
|
Pure assignment functions do not canonicalize the assigned variable.
|
|||
|
It is the responsibility of the user to canonicalize the assigned
|
|||
|
variable before any arithmetic operations are performed on that
|
|||
|
variable. *Note that this is an incompatible change from version 1 of
|
|||
|
the library.*
|
|||
|
|
|||
|
- Function: void mpq_canonicalize (mpq_t OP)
|
|||
|
Remove any factors that are common to the numerator and
|
|||
|
denominator of OP, and make the denominator positive.
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* Initializing Rationals::
|
|||
|
* Assigning Rationals::
|
|||
|
* Simultaneous Integer Init & Assign::
|
|||
|
* Comparing Rationals::
|
|||
|
* Applying Integer Functions::
|
|||
|
* Miscellaneous Rational Functions::
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Initializing Rationals, Next: Assigning Rationals, Prev: Rational Number Functions, Up: Rational Number Functions
|
|||
|
|
|||
|
Initialization and Assignment Functions
|
|||
|
=======================================
|
|||
|
|
|||
|
- Function: void mpq_init (mpq_t DEST_RATIONAL)
|
|||
|
Initialize DEST_RATIONAL and set it to 0/1. Each variable should
|
|||
|
normally only be initialized once, or at least cleared out (using
|
|||
|
the function `mpq_clear') between each initialization.
|
|||
|
|
|||
|
- Function: void mpq_clear (mpq_t RATIONAL_NUMBER)
|
|||
|
Free the space occupied by RATIONAL_NUMBER. Make sure to call this
|
|||
|
function for all `mpq_t' variables when you are done with them.
|
|||
|
|
|||
|
- Function: void mpq_set (mpq_t ROP, mpq_t OP)
|
|||
|
- Function: void mpq_set_z (mpq_t ROP, mpz_t OP)
|
|||
|
Assign ROP from OP.
|
|||
|
|
|||
|
- Function: void mpq_set_ui (mpq_t ROP, unsigned long int OP1,
|
|||
|
unsigned long int OP2)
|
|||
|
- Function: void mpq_set_si (mpq_t ROP, signed long int OP1, unsigned
|
|||
|
long int OP2)
|
|||
|
Set the value of ROP to OP1/OP2. Note that if OP1 and OP2 have
|
|||
|
common factors, ROP has to be passed to `mpq_canonicalize' before
|
|||
|
any operations are performed on ROP.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Assigning Rationals, Next: Comparing Rationals, Prev: Initializing Rationals, Up: Rational Number Functions
|
|||
|
|
|||
|
Arithmetic Functions
|
|||
|
====================
|
|||
|
|
|||
|
- Function: void mpq_add (mpq_t SUM, mpq_t ADDEND1, mpq_t ADDEND2)
|
|||
|
Set SUM to ADDEND1 + ADDEND2.
|
|||
|
|
|||
|
- Function: void mpq_sub (mpq_t DIFFERENCE, mpq_t MINUEND, mpq_t
|
|||
|
SUBTRAHEND)
|
|||
|
Set DIFFERENCE to MINUEND - SUBTRAHEND.
|
|||
|
|
|||
|
- Function: void mpq_mul (mpq_t PRODUCT, mpq_t MULTIPLIER, mpq_t
|
|||
|
MULTIPLICAND)
|
|||
|
Set PRODUCT to MULTIPLIER times MULTIPLICAND.
|
|||
|
|
|||
|
- Function: void mpq_div (mpq_t QUOTIENT, mpq_t DIVIDEND, mpq_t
|
|||
|
DIVISOR)
|
|||
|
Set QUOTIENT to DIVIDEND/DIVISOR.
|
|||
|
|
|||
|
- Function: void mpq_neg (mpq_t NEGATED_OPERAND, mpq_t OPERAND)
|
|||
|
Set NEGATED_OPERAND to -OPERAND.
|
|||
|
|
|||
|
- Function: void mpq_inv (mpq_t INVERTED_NUMBER, mpq_t NUMBER)
|
|||
|
Set INVERTED_NUMBER to 1/NUMBER. If the new denominator is zero,
|
|||
|
this routine will divide by zero.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Comparing Rationals, Next: Applying Integer Functions, Prev: Assigning Rationals, Up: Rational Number Functions
|
|||
|
|
|||
|
Comparison Functions
|
|||
|
====================
|
|||
|
|
|||
|
- Function: int mpq_cmp (mpq_t OP1, mpq_t OP2)
|
|||
|
Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
|
|||
|
if OP1 = OP2, and a negative value if OP1 < OP2.
|
|||
|
|
|||
|
To determine if two rationals are equal, `mpq_equal' is faster than
|
|||
|
`mpq_cmp'.
|
|||
|
|
|||
|
- Macro: int mpq_cmp_ui (mpq_t OP1, unsigned long int NUM2, unsigned
|
|||
|
long int DEN2)
|
|||
|
Compare OP1 and NUM2/DEN2. Return a positive value if OP1 >
|
|||
|
NUM2/DEN2, zero if OP1 = NUM2/DEN2, and a negative value if OP1 <
|
|||
|
NUM2/DEN2.
|
|||
|
|
|||
|
This routine allows that NUM2 and DEN2 have common factors.
|
|||
|
|
|||
|
This function is actually implemented as a macro. It evaluates its
|
|||
|
arguments multiple times.
|
|||
|
|
|||
|
- Macro: int mpq_sgn (mpq_t OP)
|
|||
|
Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.
|
|||
|
|
|||
|
This function is actually implemented as a macro. It evaluates its
|
|||
|
arguments multiple times.
|
|||
|
|
|||
|
- Function: int mpq_equal (mpq_t OP1, mpq_t OP2)
|
|||
|
Return non-zero if OP1 and OP2 are equal, zero if they are
|
|||
|
non-equal. Although `mpq_cmp' can be used for the same purpose,
|
|||
|
this function is much faster.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Applying Integer Functions, Next: Miscellaneous Rational Functions, Prev: Comparing Rationals, Up: Rational Number Functions
|
|||
|
|
|||
|
Applying Integer Functions to Rationals
|
|||
|
=======================================
|
|||
|
|
|||
|
The set of `mpq' functions is quite small. In particular, there are
|
|||
|
no functions for either input or output. But there are two macros that
|
|||
|
allow us to apply any `mpz' function on the numerator or denominator of
|
|||
|
a rational number. If these macros are used to assign to the rational
|
|||
|
number, `mpq_canonicalize' normally need to be called afterwards.
|
|||
|
|
|||
|
- Macro: mpz_t mpq_numref (mpq_t OP)
|
|||
|
- Macro: mpz_t mpq_denref (mpq_t OP)
|
|||
|
Return a reference to the numerator and denominator of OP,
|
|||
|
respectively. The `mpz' functions can be used on the result of
|
|||
|
these macros.
|
|||
|
|
|||
|
|
|||
|
File: gmp.info, Node: Miscellaneous Rational Functions, Prev: Applying Integer Functions, Up: Rational Number Functions
|
|||
|
|
|||
|
Miscellaneous Functions
|
|||
|
=======================
|
|||
|
|
|||
|
- Function: double mpq_get_d (mpq_t OP)
|
|||
|
Convert OP to a double.
|
|||
|
|
|||
|
These functions assign between either the numerator or denominator
|
|||
|
of a rational, and an integer. Instead of using these functions, it is
|
|||
|
preferable to use the more general mechanisms `mpq_numref' and
|
|||
|
`mpq_denref', together with `mpz_set'.
|
|||
|
|
|||
|
- Function: void mpq_set_num (mpq_t RATIONAL, mpz_t NUMERATOR)
|
|||
|
Copy NUMERATOR to the numerator of RATIONAL. When this risks to
|
|||
|
make the numerator and denominator of RATIONAL have common
|
|||
|
factors, you have to pass RATIONAL to `mpq_canonicalize' before
|
|||
|
any operations are performed on RATIONAL.
|
|||
|
|
|||
|
This function is equivalent to `mpz_set (mpq_numref (RATIONAL),
|
|||
|
NUMERATOR)'.
|
|||
|
|
|||
|
- Function: void mpq_set_den (mpq_t RATIONAL, mpz_t DENOMINATOR)
|
|||
|
Copy DENOMINATOR to the denominator of RATIONAL. When this risks
|
|||
|
to make the numerator and denominator of RATIONAL have common
|
|||
|
factors, or if the denominator might be negative, you have to pass
|
|||
|
RATIONAL to `mpq_canonicalize' before any operations are performed
|
|||
|
on RATIONAL.
|
|||
|
|
|||
|
*In version 1 of the library, negative denominators were handled by
|
|||
|
copying the sign to the numerator. That is no longer done.*
|
|||
|
|
|||
|
This function is equivalent to `mpz_set (mpq_denref (RATIONAL),
|
|||
|
DENOMINATORS)'.
|
|||
|
|
|||
|
- Function: void mpq_get_num (mpz_t NUMERATOR, mpq_t RATIONAL)
|
|||
|
Copy the numerator of RATIONAL to the integer NUMERATOR, to
|
|||
|
prepare for integer operations on the numerator.
|
|||
|
|
|||
|
This function is equivalent to `mpz_set (NUMERATOR, mpq_numref
|
|||
|
(RATIONAL))'.
|
|||
|
|
|||
|
- Function: void mpq_get_den (mpz_t DENOMINATOR, mpq_t RATIONAL)
|
|||
|
Copy the denominator of RATIONAL to the integer DENOMINATOR, to
|
|||
|
prepare for integer operations on the denominator.
|
|||
|
|
|||
|
This function is equivalent to `mpz_set (DENOMINATOR, mpq_denref
|
|||
|
(RATIONAL))'.
|
|||
|
|