1292 lines
51 KiB
Plaintext
1292 lines
51 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@comment %**start of header
|
|
@setfilename gmp.info
|
|
@settitle GNU MP 1.3.2
|
|
@synindex tp fn
|
|
@c footnotestyle separate
|
|
@c paragraphindent 2
|
|
@comment %**end of header
|
|
|
|
@c smallbook
|
|
|
|
@iftex
|
|
@finalout
|
|
@end iftex
|
|
|
|
@c Note: the edition number is listed in *three* places; please update
|
|
@c all three. Also, update the month and year where appropriate.
|
|
|
|
@c ==> Update edition number for settitle and subtitle, and in the
|
|
@c ==> following paragraph; update date, too.
|
|
|
|
@ifinfo
|
|
This file documents GNU MP, a library for arbitrary-precision integer
|
|
and rational number arithmetic.
|
|
|
|
This is a draft edition of the documentation, last updated May 20 1993.
|
|
|
|
Copyright (C) 1991, 1993 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.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through TeX and print the
|
|
results, provided the printed document carries copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the entire
|
|
resulting derived work is distributed under the terms of a permission
|
|
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.
|
|
@end ifinfo
|
|
|
|
@setchapternewpage odd
|
|
@titlepage
|
|
@c use the new format for titles
|
|
|
|
@title GNU MP
|
|
@subtitle The GNU Multiple Precision Arithmetic Library
|
|
@subtitle Edition 1.3.2
|
|
@subtitle May 1993
|
|
|
|
@author by Torbj@"orn Granlund
|
|
|
|
@comment Include the Distribution inside the titlepage so
|
|
@c that headings are turned off.
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 1991, 1993 Free Software Foundation, Inc.
|
|
|
|
@sp 2
|
|
|
|
Published by the Free Software Foundation @*
|
|
675 Massachusetts Avenue, @*
|
|
Cambridge, MA 02139 USA @*
|
|
|
|
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.
|
|
@end titlepage
|
|
|
|
@ifinfo
|
|
@node Top, Copying, (dir), (dir)
|
|
@end ifinfo
|
|
|
|
@menu
|
|
* Copying:: GMP Copying Conditions.
|
|
* Intro:: Introduction to GMP.
|
|
* Nomenclature:: Terminology and basic data types.
|
|
* Initialization:: Initialization of multi-precision number objects.
|
|
* Integer Functions:: Functions for arithmetic on signed integers.
|
|
* Rational Number Functions:: Functions for arithmetic on rational numbers.
|
|
* Low-level Functions:: Fast functions for natural numbers.
|
|
* BSD Compatible Functions:: All functions found in BSD MP (somewhat faster).
|
|
* Miscellaneous Functions:: Functions that do particular things.
|
|
* Custom Allocation:: How to customize the internal allocation.
|
|
* Reporting Bugs:: Help us to improve this library.
|
|
|
|
* References::
|
|
* Concept Index::
|
|
* Function Index::
|
|
@end menu
|
|
|
|
@node Copying, Intro, Top, Top
|
|
@comment node-name, next, previous, up
|
|
@unnumbered GNU MP Copying Conditions
|
|
@cindex Copying conditions
|
|
@cindex Conditions for copying GNU MP
|
|
|
|
This library is @dfn{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.@refill
|
|
|
|
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.@refill
|
|
|
|
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 GMP 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.@refill
|
|
|
|
Also, for our own protection, we must make certain that everyone finds
|
|
out that there is no warranty for the GMP 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.@refill
|
|
|
|
The precise conditions of the license for the GMP library are found in
|
|
the General Public License that accompany the source code.@refill
|
|
|
|
@node Intro, Initialization, Copying, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Introduction to MP
|
|
@cindex Introduction
|
|
@cindex Overview
|
|
|
|
GNU MP is a portable library for arbitrary precision integer and
|
|
rational number arithmetic.@footnote{The limit of the precision is set by the
|
|
available memory in your computer.} It aims to provide the fastest
|
|
possible arithmetic for all applications that need more than two words
|
|
of integer precision.
|
|
|
|
Most often, applications tend to use just a few words of precision;
|
|
but some applications may need thousands of words. GNU MP is designed
|
|
to give good performance for both kinds of applications, by choosing
|
|
algorithms based on the sizes of the operands.
|
|
|
|
There are five groups of functions in the MP library:
|
|
|
|
@enumerate
|
|
@item
|
|
Functions for signed integer arithmetic, with names
|
|
beginning with @code{mpz_}.
|
|
|
|
@item
|
|
Functions for rational number arithmetic, with names beginning with
|
|
@code{mpq_}.
|
|
|
|
@item
|
|
Functions compatible with Berkeley MP, such as @code{itom}, @code{madd},
|
|
and @code{mult}.
|
|
|
|
@item
|
|
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 @code{mpn_}.
|
|
|
|
@item
|
|
Miscellaneous functions.
|
|
@end enumerate
|
|
|
|
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.) Multi-precision numbers, whether
|
|
output or input, are always passed as addresses to the declared type.
|
|
|
|
@menu
|
|
* Nomenclature::
|
|
* Thanks::
|
|
@end menu
|
|
|
|
@node Nomenclature, Thanks, Intro, Intro
|
|
@comment node-name, next, previous, up
|
|
@section Nomenclature and Data Types
|
|
@cindex nomenclature
|
|
|
|
@cindex integer
|
|
@tindex @code{MP_INT}
|
|
In this manual, @dfn{integer} means a multiple precision integer, as
|
|
used in the MP package. The C data type for such integers is
|
|
@code{MP_INT}. For example:
|
|
|
|
@example
|
|
MP_INT sum;
|
|
|
|
struct foo @{ MP_INT x, y; @};
|
|
|
|
MP_INT vec[20];
|
|
@end example
|
|
|
|
@cindex rational number
|
|
@tindex @code{MP_RAT}
|
|
@dfn{Rational number} means a multiple precision fraction. The C data
|
|
type for these fractions is @code{MP_RAT}. For example:
|
|
|
|
@example
|
|
MP_RAT quotient;
|
|
@end example
|
|
|
|
@cindex limb
|
|
A @dfn{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 bits.
|
|
|
|
@node Thanks,, Nomenclature, Intro
|
|
@comment node-name, next, previous, up
|
|
@section Thanks
|
|
|
|
I would like to thank Gunnar Sjoedin and Hans Riesel for their help with
|
|
mathematical problems, Richard Stallman for his help with design issues
|
|
and for revising this manual, Brian Beuning and Doug Lea for their
|
|
testing of various versions of the library, and Joachim Hollman for
|
|
his many valuable suggestions.
|
|
|
|
Special thanks to Brian Beuning, he has shaked out many bugs from early
|
|
versions of the code!
|
|
|
|
John Amanatides of York University in Canada contributed the function
|
|
@code{mpz_probab_prime_p}.
|
|
|
|
@node Initialization, Integer Functions, Intro, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Initialization
|
|
|
|
Before you can use a variable or object of type @code{MP_INT} or
|
|
@code{MP_RAT}, you must initialize it. This fills in the components
|
|
that point to dynamically allocated space for the limbs of the number.
|
|
|
|
When you are finished using the object, you should clear out the object.
|
|
This frees the dynamic space that it points to, so the space can be used
|
|
again.
|
|
|
|
Once you have initialized the object, you need not be concerned about
|
|
allocating additional space. The functions in the MP package
|
|
automatically allocate additional space when the object does not already
|
|
have enough space. They do not, however, reduce the space in use when a
|
|
smaller number is stored in the object. Most of the time, this policy
|
|
is best, since it avoids frequent re-allocation. If you want to reduce
|
|
the space in an object to the minimum needed, you can do
|
|
@code{_mpz_realloc (&@var{object}, mpz_size (&@var{object}))}.
|
|
|
|
The functions to initialize numbers are @code{mpz_init} (for @code{MP_INT}) and
|
|
@code{mpq_init} (for @code{MP_RAT}).
|
|
|
|
@code{mpz_init} allocates space for the limbs, and stores a pointer
|
|
to that space in the @code{MP_INT} object. It also stores the value 0
|
|
in the object.
|
|
|
|
In the same manner, @code{mpq_init} allocates space for the numerator
|
|
and denominator limbs, and stores pointers to these spaces in the @code{MP_RAT}
|
|
object.
|
|
|
|
To clear out a number object, use @code{mpz_clear} and @code{mpq_clear},
|
|
respectively.
|
|
|
|
Here is an example of use:
|
|
|
|
@example
|
|
@{
|
|
MP_INT temp;
|
|
mpz_init (&temp);
|
|
|
|
@dots{} @r{store and read values in @code{temp} zero or more times} @dots{}
|
|
|
|
mpz_clear (&temp):
|
|
@}
|
|
@end example
|
|
|
|
You might be tempted to copy an integer from one object to another like
|
|
this:
|
|
|
|
@example
|
|
MP_INT x, y;
|
|
|
|
x = y;
|
|
@end example
|
|
|
|
Although valid C, @strong{this is an error.} Rather than copying the
|
|
integer value from @code{y} to @code{x} it will make the two variables
|
|
share storage. Subsequent assignments to one variable would change the
|
|
other mysteriously. And if you were to clear out both variables
|
|
subsequently, you would confuse @code{malloc} and cause your program to
|
|
crash.
|
|
|
|
To copy the value properly, you must use the function @code{mpz_set}.
|
|
(@pxref{Assigning Integers})
|
|
|
|
@node Integer Functions, Rational Number Functions, Initialization, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Integer Functions
|
|
@cindex Integer functions
|
|
|
|
This chapter describes the MP functions for performing integer arithmetic.
|
|
|
|
The integer functions use arguments and values of type
|
|
pointer-to-@code{MP_INT} (@pxref{Nomenclature}). The type @code{MP_INT}
|
|
is a structure, but applications should not refer directly to its
|
|
components. Include the header @file{gmp.h} to get the definition of
|
|
@code{MP_INT}.
|
|
|
|
@menu
|
|
* Initializing Integers::
|
|
* Assigning Integers::
|
|
* Simultaneous Integer Init & Assign::
|
|
* Converting Integers::
|
|
* Integer Arithmetic::
|
|
* Logic on Integers::
|
|
* I/O of Integers::
|
|
@end menu
|
|
|
|
@node Initializing Integers, Assigning Integers, , Integer Functions
|
|
@comment node-name, next, previous, up
|
|
@section Initializing Integer Objects
|
|
|
|
Most of the functions for integer arithmetic assume that the output is
|
|
stored in an object already initialized. For example, @code{mpz_add}
|
|
stores the result of addition (@pxref{Integer Arithmetic}). Thus, you
|
|
must initialize the object before storing the first value in it. You
|
|
can do this separately by calling the function @code{mpz_init}.
|
|
|
|
@deftypefun void mpz_init (MP_INT *@var{integer})
|
|
Initialize @var{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 @code{mpz_clear}) between each initialization.
|
|
@end deftypefun
|
|
|
|
Here is an example of using @code{mpz_init}:
|
|
|
|
@example
|
|
@{
|
|
MP_INT integ;
|
|
mpz_init (&integ);
|
|
@dots{}
|
|
mpz_add (&integ, @dots{});
|
|
@dots{}
|
|
mpz_sub (&integ, @dots{});
|
|
|
|
/* Unless you are now exiting the program, do ... */
|
|
mpz_clear (&integ);
|
|
@}
|
|
@end example
|
|
|
|
@noindent
|
|
As you can see, you can store new values any number of times, once an
|
|
object is initialized.
|
|
|
|
@deftypefun void mpz_clear (MP_INT *@var{integer})
|
|
Free the limb space occupied by @var{integer}. Make sure to call this
|
|
function for all @code{MP_INT} variables when you are done with them.
|
|
@end deftypefun
|
|
|
|
@deftypefun {void *} _mpz_realloc (MP_INT *@var{integer}, mp_size @var{new_alloc})
|
|
Change the limb space allocation to @var{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.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_array_init (MP_INT @var{integer_array}[], size_t @var{array_size}, mp_size @var{fixed_num_limbs})
|
|
Allocate @strong{fixed} limb space for all @var{array_size} integers in
|
|
@var{integer_array}. The fixed allocation for each integer in the array
|
|
is @var{fixed_num_limbs}. This function is useful for decreasing the
|
|
working set for some algorithms that use large integer arrays. If the
|
|
fixed space will be insufficient for storing the result of a subsequent
|
|
calculation, the result is unpredictable.
|
|
|
|
There is no way to de-allocate the storage allocated by this function. Don't
|
|
call @code{mpz_clear}!
|
|
@end deftypefun
|
|
|
|
|
|
@node Assigning Integers, Simultaneous Integer Init & Assign, Initializing Integers, Integer Functions
|
|
@comment node-name, next, previous, up
|
|
@subsection Integer Assignment Functions
|
|
@cindex Integer assignment functions
|
|
|
|
These functions assign new values to already initialized integers
|
|
(@pxref{Initializing Integers}).
|
|
|
|
@deftypefun void mpz_set (MP_INT *@var{dest_integer}, MP_INT *@var{src_integer})
|
|
Assign @var{dest_integer} from @var{src_integer}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_set_ui (MP_INT *@var{integer}, unsigned long int @var{initial_value})
|
|
Set the value of @var{integer} from @var{initial_value}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_set_si (MP_INT *@var{integer}, signed long int @var{initial_value})
|
|
Set the value of @var{integer} from @var{initial_value}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpz_set_str (MP_INT *@var{integer}, char *@var{initial_value}, int @var{base})
|
|
Set the value of @var{integer} from @var{initial_value},
|
|
a '\0'-terminated C string in base @var{base}. White space is allowed in
|
|
the string, and is simply ignored. The base may vary from 2 to 36. If
|
|
@var{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 @var{base}. Otherwise it returns @minus{}1.
|
|
@end deftypefun
|
|
|
|
|
|
@node Simultaneous Integer Init & Assign, Converting Integers, Assigning Integers, Integer Functions
|
|
@comment node-name, next, previous, up
|
|
@subsection Combined Initialization and Assignment Functions
|
|
@cindex Initialization and assignment functions, combined
|
|
|
|
For your convenience, MP provides a parallel series of
|
|
initialize-and-set arithmetic functions which initialize the output and
|
|
then store the value there. These functions' names have the form
|
|
@code{mpz_init_set@dots{}}.
|
|
|
|
Here is an example of using one:
|
|
|
|
@example
|
|
@{
|
|
MP_INT integ;
|
|
mpz_init_set_str (&integ, "3141592653589793238462643383279502884", 10);
|
|
@dots{}
|
|
mpz_sub (&integ, @dots{});
|
|
|
|
mpz_clear (&integ);
|
|
@}
|
|
@end example
|
|
|
|
Once the integer has been initialized by any of the
|
|
@code{mpz_init_set@dots{}} 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!
|
|
|
|
@deftypefun void mpz_init_set (MP_INT *@var{dest_integer}, MP_INT *@var{src_integer})
|
|
Initialize @var{dest_integer} with limb space and set the initial numeric
|
|
value from @var{src_integer}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_init_set_ui (MP_INT *@var{dest_integer}, unsigned long int @var{src_ulong})
|
|
Initialize @var{dest_integer} with limb space and set the initial numeric
|
|
value from @var{src_ulong}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_init_set_si (MP_INT *@var{dest_integer}, signed long int @var{src_slong})
|
|
Initialize @var{dest_integer} with limb space and set the initial numeric
|
|
value from @var{src_slong}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpz_init_set_str (MP_INT *@var{dest_integer}, char *@var{src_cstring}, int @var{base})
|
|
Initialize @var{dest_integer} with limb space and set the initial
|
|
numeric value from @var{src_cstring}, a '\0'-terminated C string in base
|
|
@var{base}. The base may vary from 2 to 36. There may be white space
|
|
in the string.
|
|
|
|
If the string is a correct base @var{base} number, the function returns
|
|
0; if an error occurs it returns @minus{}1. @var{dest_integer} is
|
|
initialized even if an error occurs. (I.e., you have to call mpz_clear
|
|
for it.)
|
|
@end deftypefun
|
|
|
|
|
|
@node Converting Integers, Integer Arithmetic, Simultaneous Integer Init & Assign, Integer Functions
|
|
@comment node-name, next, previous, up
|
|
@section Conversion Functions
|
|
@cindex Conversion functions
|
|
|
|
@deftypefun {unsigned long int} mpz_get_ui (MP_INT *@var{src_integer})
|
|
Return the least significant limb from @var{src_integer}. This
|
|
function together with @*
|
|
@code{mpz_div_2exp(@dots{}, @var{src_integer}, CHAR_BIT*sizeof(unsigned
|
|
long int))} can be used to extract the limbs of an integer efficiently.
|
|
@end deftypefun
|
|
|
|
@deftypefun {signed long int} mpz_get_si (MP_INT *@var{src_integer})
|
|
If @var{src_integer} fits into a @code{signed long int} return the value
|
|
of @var{src_integer}. Otherwise return the least significant bits of
|
|
@var{src_integer}, with the same sign as @var{src_integer}.
|
|
@end deftypefun
|
|
|
|
@deftypefun {char *} mpz_get_str (char *@var{string}, int @var{base}, MP_INT *@var{integer})
|
|
Convert @var{integer} to a '\0'-terminated C string in @var{string},
|
|
using base @var{base}. The base may vary from 2 to 36. If @var{string}
|
|
is NULL, space for the string is allocated using the default allocation
|
|
function.
|
|
|
|
If @var{string} 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 @var{string}, use @code{mpz_sizeinbase (@var{integer},
|
|
@var{base}) + 2}. The "+ 2" is for a possible minus sign, and for the
|
|
terminating null character. (@pxref{Miscellaneous Functions}).
|
|
|
|
This function returns a pointer to the result string.
|
|
@end deftypefun
|
|
|
|
|
|
@node Integer Arithmetic, Logic on Integers, Converting Integers, Integer Functions
|
|
@comment node-name, next, previous, up
|
|
@section Integer Arithmetic Functions
|
|
@cindex Integer arithmetic functions
|
|
@cindex Arithmetic functions
|
|
|
|
@deftypefun void mpz_add (MP_INT *@var{sum}, MP_INT *@var{addend1}, MP_INT *@var{addend2})
|
|
@end deftypefun
|
|
@deftypefun void mpz_add_ui (MP_INT *@var{sum}, MP_INT *@var{addend1}, unsigned long int @var{addend2})
|
|
Set @var{sum} to @var{addend1} + @var{addend2}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_sub (MP_INT *@var{difference}, MP_INT *@var{minuend}, MP_INT *@var{subtrahend})
|
|
@end deftypefun
|
|
@deftypefun void mpz_sub_ui (MP_INT *@var{difference}, MP_INT *@var{minuend}, unsigned long int @var{subtrahend})
|
|
Set @var{difference} to @var{minuend} @minus{} @var{subtrahend}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_mul (MP_INT *@var{product}, MP_INT *@var{multiplicator}, MP_INT *@var{multiplicand})
|
|
@end deftypefun
|
|
@deftypefun void mpz_mul_ui (MP_INT *@var{product}, MP_INT *@var{multiplicator}, unsigned long int @var{multiplicand})
|
|
Set @var{product} to @var{multiplicator} times @var{multiplicand}.
|
|
@end deftypefun
|
|
|
|
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 powm 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.
|
|
|
|
@deftypefun void mpz_div (MP_INT *@var{quotient}, MP_INT *@var{dividend}, MP_INT *@var{divisor})
|
|
@end deftypefun
|
|
@deftypefun void mpz_div_ui (MP_INT *@var{quotient}, MP_INT *@var{dividend}, unsigned long int @var{divisor})
|
|
Set @var{quotient} to @var{dividend} / @var{divisor}. The quotient is
|
|
rounded towards 0.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_mod (MP_INT *@var{remainder}, MP_INT *@var{divdend}, MP_INT *@var{divisor})
|
|
@end deftypefun
|
|
@deftypefun void mpz_mod_ui (MP_INT *@var{remainder}, MP_INT *@var{divdend}, unsigned long int @var{divisor})
|
|
Divide @var{dividend} and @var{divisor} and put the remainder in
|
|
@var{remainder}. The remainder has the same sign as the dividend, and
|
|
its absolute value is less than the absolute value of the divisor.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_divmod (MP_INT *@var{quotient}, MP_INT *@var{remainder}, MP_INT *@var{dividend}, MP_INT *@var{divisor})
|
|
@end deftypefun
|
|
@deftypefun void mpz_divmod_ui (MP_INT *@var{quotient}, MP_INT *@var{remainder}, MP_INT *@var{dividend}, unsigned long int @var{divisor})
|
|
Divide @var{dividend} and @var{divisor} and put the quotient in
|
|
@var{quotient} and the remainder in @var{remainder}. The quotient is
|
|
rounded towards 0. The remainder has the same sign as the dividend,
|
|
and its absolute value is less than the absolute value of the divisor.
|
|
|
|
If @var{quotient} and @var{remainder} are the same variable, the results
|
|
are not defined.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_mdiv (MP_INT *@var{quotient}, MP_INT *@var{dividend}, MP_INT *@var{divisor})
|
|
@end deftypefun
|
|
@deftypefun void mpz_mdiv_ui (MP_INT *@var{quotient}, MP_INT *@var{dividend}, unsigned long int @var{divisor})
|
|
Set @var{quotient} to @var{dividend} / @var{divisor}. The quotient is
|
|
rounded towards @minus{}infinity.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_mmod (MP_INT *@var{remainder}, MP_INT *@var{divdend}, MP_INT *@var{divisor})
|
|
@end deftypefun
|
|
@deftypefun {unsigned long int} mpz_mmod_ui (MP_INT *@var{remainder}, MP_INT *@var{divdend}, unsigned long int @var{divisor})
|
|
Divide @var{dividend} and @var{divisor} and put the remainder in
|
|
@var{remainder}. The remainder is always positive, and its value is
|
|
less than the value of the divisor.
|
|
|
|
For @code{mpz_mmod_ui} the remainder is returned, and if @var{remainder} is
|
|
not NULL, also stored there.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_mdivmod (MP_INT *@var{quotient}, MP_INT *@var{remainder}, MP_INT *@var{dividend}, MP_INT *@var{divisor})
|
|
@end deftypefun
|
|
@deftypefun {unsigned long int} mpz_mdivmod_ui (MP_INT *@var{quotient}, MP_INT *@var{remainder}, MP_INT *@var{dividend}, unsigned long int @var{divisor})
|
|
Divide @var{dividend} and @var{divisor} and put the quotient in
|
|
@var{quotient} and the remainder in @var{remainder}. The quotient is
|
|
rounded towards @minus{}infinity. The remainder is always positive, and its
|
|
value is less than the value of the divisor.
|
|
|
|
For @code{mpz_mdivmod_ui} the remainder is small enough to fit in an
|
|
@code{unsigned long int}, and is therefore returned. If @var{remainder}
|
|
is not NULL, the remainder is also stored there.
|
|
|
|
If @var{quotient} and @var{remainder} are the same variable, the results
|
|
are not defined.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_sqrt (MP_INT *@var{root}, MP_INT *@var{operand})
|
|
Set @var{root} to the square root of @var{operand}. The result is
|
|
rounded towards zero.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_sqrtrem (MP_INT *@var{root}, MP_INT *@var{remainder}, MP_INT *@var{operand})
|
|
Set @var{root} to the square root of @var{operand}, as with
|
|
@code{mpz_sqrt}. Set @var{remainder} to
|
|
@ifinfo
|
|
@var{operand}@minus{}@var{root}*@var{root},
|
|
@end ifinfo
|
|
@iftex
|
|
@tex
|
|
$operand - root^2$,
|
|
@end tex
|
|
@end iftex
|
|
(i.e@. zero if @var{operand} is a perfect square).
|
|
|
|
If @var{root} and @var{remainder} are the same variable, the results are
|
|
not defined.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpz_perfect_square_p (MP_INT *@var{square})
|
|
Return non-zero if @var{square} is perfect, i.e@. if the square root of
|
|
@var{square} is integral. Return zero otherwise.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpz_probab_prime_p (MP_INT *@var{n}, int @var{reps})
|
|
An implementation of the probabilistic primality test found in Knuth's
|
|
Seminumerical Algorithms book. If the function
|
|
@code{mpz_probab_prime_p(@var{n}, @var{reps})} returns 0 then @var{n} is
|
|
not prime. If it returns 1, then @var{n} is `probably' prime. The
|
|
probability of a false positive is (1/4)**@var{reps}, where @var{reps}
|
|
is the number of internal passes of the probabilistic algorithm. Knuth
|
|
indicates that 25 passes are reasonable.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_powm (MP_INT *@var{res}, MP_INT *@var{base}, MP_INT *@var{exp}, MP_INT *@var{mod})
|
|
@end deftypefun
|
|
@deftypefun void mpz_powm_ui (MP_INT *@var{res}, MP_INT *@var{base}, unsigned long int @var{exp}, MP_INT *@var{mod})
|
|
Set @var{res} to (@var{base} raised to @var{exp}) modulo @var{mod}.
|
|
If @var{exp} is negative, the result is undefined.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_pow_ui (MP_INT *@var{res}, MP_INT *@var{base}, unsigned long int @var{exp})
|
|
Set @var{res} to @var{base} raised to @var{exp}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_fac_ui (MP_INT *@var{res}, unsigned long int @var{n})
|
|
Set @var{res} @var{n}!, the factorial of n.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_gcd (MP_INT *@var{res}, MP_INT *@var{operand1}, MP_INT *@var{operand2})
|
|
Set @var{res} to the greatest common divisor of @var{operand1} and
|
|
@var{operand2}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_gcdext (MP_INT *@var{g}, MP_INT *@var{s}, MP_INT *@var{t}, MP_INT *@var{a}, MP_INT *@var{b})
|
|
Compute @var{g}, @var{s}, and @var{t}, such that @var{a}@var{s} +
|
|
@var{b}@var{t} = @var{g} = @code{gcd} (@var{a}, @var{b}). If @var{t} is
|
|
NULL, that argument is not computed.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_neg (MP_INT *@var{negated_operand}, MP_INT *@var{operand})
|
|
Set @var{negated_operand} to @minus{}@var{operand}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_abs (MP_INT *@var{positive_operand}, MP_INT *@var{signed_operand})
|
|
Set @var{positive_operand} to the absolute value of @var{signed_operand}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpz_cmp (MP_INT *@var{operand1}, MP_INT *@var{operand2})
|
|
@end deftypefun
|
|
@deftypefun int mpz_cmp_ui (MP_INT *@var{operand1}, unsigned long int @var{operand2})
|
|
@end deftypefun
|
|
@deftypefun int mpz_cmp_si (MP_INT *@var{operand1}, signed long int @var{operand2})
|
|
Compare @var{operand1} and @var{operand2}. Return a positive value if
|
|
@var{operand1} > @var{operand2}, zero if @var{operand1} = @var{operand2},
|
|
and a negative value if @var{operand1} < @var{operand2}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_mul_2exp (MP_INT *@var{product}, MP_INT *@var{multiplicator}, unsigned long int @var{exponent_of_2})
|
|
Set @var{product} to @var{multiplicator} times 2 raised to
|
|
@var{exponent_of_2}. This operation can also be defined as a left shift,
|
|
@var{exponent_of_2} steps.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_div_2exp (MP_INT *@var{quotient}, MP_INT *@var{dividend}, unsigned long int @var{exponent_of_2})
|
|
Set @var{quotient} to @var{dividend} divided by 2 raised to
|
|
@var{exponent_of_2}. This operation can also be defined as a right
|
|
shift, @var{exponent_of_2} steps, but unlike the >> operator in
|
|
C, the result is rounded towards 0.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_mod_2exp (MP_INT *@var{remainder}, MP_INT *@var{dividend}, unsigned long int @var{exponent_of_2})
|
|
Set @var{remainder} to @var{dividend} mod (2 raised to
|
|
@var{exponent_of_2}). The sign of @var{remainder} will have the same sign
|
|
as @var{dividend}.
|
|
|
|
This operation can also be defined as a masking of the
|
|
@var{exponent_of_2} least significant bits.
|
|
@end deftypefun
|
|
|
|
@node Logic on Integers, I/O of Integers, Integer Arithmetic, Integer Functions
|
|
@comment node-name, next, previous, up
|
|
@section Logical Functions
|
|
@cindex Logical functions
|
|
|
|
@deftypefun void mpz_and (MP_INT *@var{conjunction}, MP_INT *@var{operand1}, MP_INT *@var{operand2})
|
|
Set @var{conjunction} to @var{operand1} logical-and @var{operand2}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_ior (MP_INT *@var{disjunction}, MP_INT *@var{operand1}, MP_INT *@var{operand2})
|
|
Set @var{disjunction} to @var{operand1} inclusive-or @var{operand2}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_xor (MP_INT *@var{disjunction}, MP_INT *@var{operand1}, MP_INT *@var{operand2})
|
|
Set @var{disjunction} to @var{operand1} exclusive-or @var{operand2}.
|
|
|
|
This function is missing in the current release.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_com (MP_INT *@var{complemented_operand}, MP_INT *@var{operand})
|
|
Set @var{complemented_operand} to the one's complement of @var{operand}.
|
|
@end deftypefun
|
|
|
|
@node I/O of Integers,, Logic on Integers, Integer Functions
|
|
@comment node-name, next, previous, up
|
|
@section Input and Output Functions
|
|
@cindex Input and output functions
|
|
@cindex Output functions
|
|
@cindex I/O functions
|
|
|
|
Functions that perform input from a standard I/O stream, and functions for
|
|
output conversion.
|
|
|
|
@deftypefun void mpz_inp_raw (MP_INT *@var{integer}, FILE *@var{stream})
|
|
Input from standard I/O stream @var{stream} in the format written by
|
|
@code{mpz_out_raw}, and put the result in @var{integer}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_inp_str (MP_INT *@var{integer}, FILE *@var{stream}, int @var{base})
|
|
Input a string in base @var{base} from standard I/O stream @var{stream},
|
|
and put the read integer in @var{integer}. The base may vary from 2 to
|
|
36. If @var{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.
|
|
@end deftypefun
|
|
|
|
|
|
@deftypefun void mpz_out_raw (FILE *@var{stream}, MP_INT *@var{integer})
|
|
Output @var{integer} on standard I/O stream @var{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.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_out_str (FILE *@var{stream}, int @var{base}, MP_INT *@var{integer})
|
|
Output @var{integer} on standard I/O stream @var{stream}, as a string of
|
|
digits in base @var{base}. The base may vary from 2 to 36.
|
|
@end deftypefun
|
|
|
|
|
|
@node Rational Number Functions, Low-level Functions, Integer Functions, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Rational Number Functions
|
|
@cindex Rational number functions
|
|
|
|
All rational arithmetic functions canonicalize the result, so that the
|
|
denominator and the numerator have no common factors. Zero has the
|
|
unique representation 0/1.
|
|
|
|
The set of functions is quite small. Maybe it will be extended in a
|
|
future release.
|
|
|
|
@deftypefun void mpq_init (MP_RAT *@var{dest_rational})
|
|
Initialize @var{dest_rational} with limb space and set the initial
|
|
numeric value to 0/1. Each variable should normally only be initialized
|
|
once, or at least cleared out (using the function @code{mpq_clear})
|
|
between each initialization.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_clear (MP_RAT *@var{rational_number})
|
|
Free the limb space occupied by @var{rational_number}. Make sure to
|
|
call this function for all @code{MP_RAT} variables when you are done
|
|
with them.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_set (MP_RAT *@var{dest_rational}, MP_RAT *@var{src_rational})
|
|
Assign @var{dest_rational} from @var{src_rational}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_set_ui (MP_RAT *@var{rational_number}, unsigned long int @var{numerator}, unsigned long int @var{denominator})
|
|
Set the value of @var{rational_number} to
|
|
@var{numerator}/@var{denominator}. If @var{numerator} and
|
|
@var{denominator} have common factors, they are divided out before
|
|
@var{rational_number} is assigned.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_set_si (MP_RAT *@var{rational_number}, signed long int @var{numerator}, unsigned long int @var{denominator})
|
|
Like @code{mpq_set_ui}, but @var{numerator} is signed.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_add (MP_RAT *@var{sum}, MP_RAT *@var{addend1}, MP_RAT *@var{addend2})
|
|
Set @var{sum} to @var{addend1} + @var{addend2}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_sub (MP_RAT *@var{difference}, MP_RAT *@var{minuend}, MP_RAT *@var{subtrahend})
|
|
Set @var{difference} to @var{minuend} @minus{} @var{subtrahend}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_mul (MP_RAT *@var{product}, MP_RAT *@var{multiplicator}, MP_RAT *@var{multiplicand})
|
|
Set @var{product} to @var{multiplicator} * @var{multiplicand}
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_div (MP_RAT *@var{quotient}, MP_RAT *@var{dividend}, MP_RAT *@var{divisor})
|
|
Set @var{quotient} to @var{dividend} / @var{divisor}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_neg (MP_RAT *@var{negated_operand}, MP_RAT *@var{operand})
|
|
Set @var{negated_operand} to @minus{}@var{operand}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpq_cmp (MP_RAT *@var{operand1}, MP_RAT *@var{operand2})
|
|
Compare @var{operand1} and @var{operand2}. Return a positive value if
|
|
@var{operand1} > @var{operand2}, zero if @var{operand1} = @var{operand2},
|
|
and a negative value if @var{operand1} < @var{operand2}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_inv (MP_RAT *@var{inverted_number}, MP_RAT *@var{number})
|
|
Invert @var{number} by swapping the numerator and denominator. If the
|
|
new denominator becomes zero, this routine will divide by zero.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_set_num (MP_RAT *@var{rational_number}, MP_INT *@var{numerator})
|
|
Make @var{numerator} become the numerator of @var{rational_number} by
|
|
copying.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_set_den (MP_RAT *@var{rational_number}, MP_INT *@var{denominator})
|
|
Make @var{denominator} become the denominator of @var{rational_number}
|
|
by copying. If @var{denominator} < 0 the denominator of
|
|
@var{rational_number} is set to the absolute value of @var{denominator},
|
|
and the sign of the numerator of @var{rational_number} is changed.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_get_num (MP_INT *@var{numerator}, MP_RAT *@var{rational_number})
|
|
Copy the numerator of @var{rational_number} to the integer
|
|
@var{numerator}, to prepare for integer operations on the numerator.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpq_get_den (MP_INT *@var{denominator}, MP_RAT *@var{rational_number})
|
|
Copy the denominator of @var{rational_number} to the integer
|
|
@var{denominator}, to prepare for integer operations on the denominator.
|
|
@end deftypefun
|
|
|
|
|
|
@node Low-level Functions, BSD Compatible Functions, Rational Number Functions, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Low-level Functions
|
|
@cindex Low-level functions
|
|
|
|
@c 1. Some of these function clobber input operands.
|
|
@c
|
|
|
|
@strong{The next release of the GNU MP library (2.0) will include
|
|
changes to some mpn functions. Programs that use these functions
|
|
according to the descriptions below will therefore not work with the
|
|
next release.}
|
|
|
|
The low-level function layer is designed to be as fast as possible,
|
|
@strong{not} to provide a coherent calling interface. The different
|
|
functions have similar interfaces, but there are variations that might
|
|
be confusing. These functions do as little as possible apart from the
|
|
real multiple precision computation, so that no time is spent on things
|
|
that not all callers need.
|
|
|
|
A source operand is specified by a pointer to the least significant limb
|
|
and a limb count. A destination operand is specified by just a pointer.
|
|
It is the responsability of the caller to ensure that the destination
|
|
has enough space for storing the result.
|
|
|
|
With this way of specifying source operands, it is possible to perform
|
|
computations on subranges of an argument, and store the result into a
|
|
subrange of a destination.
|
|
|
|
All these functions require that the operands are normalized in the
|
|
sense that the most significant limb must be non-zero. (A future release
|
|
of might drop this requirement.)
|
|
|
|
The low-level layer is the base for the implementation of the
|
|
@code{mpz_} and @code{mpq_} layers.
|
|
|
|
The code below adds the number beginning at @var{src1_ptr} and the
|
|
number beginning at @var{src2_ptr} and writes the sum at @var{dest_ptr}.
|
|
A constraint for @code{mpn_add} is that @var{src1_size} must not be
|
|
smaller that @var{src2_size}.
|
|
|
|
@example
|
|
mpn_add (dest_ptr, src1_ptr, src1_size, src2_ptr, src2_size)
|
|
@end example
|
|
|
|
In the description below, a source operand is identified by the pointer
|
|
to the least significant limb, and the limb count in braces.
|
|
|
|
@deftypefun mp_size mpn_add (mp_ptr @var{dest_ptr}, mp_srcptr @var{src1_ptr}, mp_size @var{src1_size}, mp_srcptr @var{src2_ptr}, mp_size @var{src2_size})
|
|
Add @{@var{src1_ptr}, @var{src1_size}@} and @{@var{src2_ptr},
|
|
@var{src2_size}@}, and write the @var{src1_size} least significant limbs
|
|
of the result to @var{dest_ptr}. Carry-out, either 0 or 1, is returned.
|
|
|
|
This function requires that @var{src1_size} is greater than or equal to
|
|
@var{src2_size}.
|
|
@end deftypefun
|
|
|
|
@deftypefun mp_size mpn_sub (mp_ptr @var{dest_ptr}, mp_srcptr @var{src1_ptr}, mp_size @var{src1_size}, mp_srcptr @var{src2_ptr}, mp_size @var{src2_size})
|
|
Subtarct @{@var{src2_ptr}, @var{src2_size}@} from @{@var{src1_ptr},
|
|
@var{src1_size}@}, and write the result to @var{dest_ptr}.
|
|
|
|
Return 1 if the minuend < the subtrahend. Otherwise, return the
|
|
negative difference between the number of words in the result and the
|
|
minuend. I.e@. return 0 if the result has @var{src1_size} words, @minus{}1 if
|
|
it has @var{src1_size} @minus{} 1 words, etc.
|
|
|
|
This function requires that @var{src1_size} is greater than or equal to
|
|
@var{src2_size}.
|
|
@end deftypefun
|
|
|
|
@deftypefun mp_size mpn_mul (mp_ptr @var{dest_ptr}, mp_srcptr @var{src1_ptr}, mp_size @var{src1_size}, mp_srcptr @var{src2_ptr}, mp_size @var{src2_size})
|
|
Multiply @{@var{src1_ptr}, @var{src1_size}@} and @{@var{src2_ptr},
|
|
@var{src2_size}@}, and write the result to @var{dest_ptr}. The exact
|
|
size of the result is returned.
|
|
|
|
The destination has to have space for @var{src1_size} + @var{src1_size}
|
|
limbs, even if the result might be one limb smaller.
|
|
|
|
This function requires that @var{src1_size} is greater than or equal to
|
|
@var{src2_size}. The destination must be distinct from either input
|
|
operands.
|
|
@end deftypefun
|
|
|
|
@deftypefun mp_size mpn_div (mp_ptr @var{dest_ptr}, mp_ptr @var{src1_ptr}, mp_size @var{src1_size}, mp_srcptr @var{src2_ptr}, mp_size @var{src2_size})
|
|
Divide @{@var{src1_ptr}, @var{src1_size}@} by @{@var{src2_ptr},
|
|
@var{src2_size}@}, and write the quotient to @var{dest_ptr}, and the
|
|
remainder to @var{src1_ptr}.
|
|
|
|
Return 0 if the quotient size is at most (@var{src1_size} @minus{}
|
|
@var{src2_size}), and 1 if the quotient size is at most (@var{src1_size}
|
|
@minus{} @var{src2_size} + 1). The caller has to check the most significant limb
|
|
to find out the exact size.
|
|
|
|
The most significant bit of the most significant limb of the divisor
|
|
has to be set.
|
|
|
|
This function requires that @var{src1_size} is greater than or equal to
|
|
@var{src2_size}. The quotient, pointed to by @var{dest_ptr}, must be
|
|
distinct from either input operands.
|
|
@end deftypefun
|
|
|
|
@deftypefun mp_limb mpn_lshift (mp_ptr @var{dest_ptr}, mp_srcptr @var{src_ptr}, mp_size @var{src_size}, unsigned long int @var{count})
|
|
Shift @{@var{src_ptr}, @var{src_size}@} @var{count} bits to the left, and
|
|
write the @var{src_size} least significant limbs of the result to
|
|
@var{dest_ptr}. @var{count} might be in the range 1 to n @minus{} 1, on an n-bit
|
|
machine. The limb shifted out is returned.
|
|
|
|
Overlapping of the destination space and the source space is allowed in this
|
|
function, provdied @var{dest_ptr} >= @var{src_ptr}.
|
|
@end deftypefun
|
|
|
|
@deftypefun mp_size mpn_rshift (mp_ptr @var{dest_ptr}, mp_srcptr @var{src_ptr}, mp_size @var{src_size}, unsigned long int @var{count})
|
|
Shift @{@var{src_ptr}, @var{src_size}@} @var{count} bits to the right, and
|
|
write the @var{src_size} least significant limbs of the result to
|
|
@var{dest_ptr}. @var{count} might be in the range 1 to n @minus{} 1, on an n-bit
|
|
machine. The size of the result is returned.
|
|
|
|
Overlaping of the destination space and the source space is allowed in this
|
|
function, provdied @var{dest_ptr} <= @var{src_ptr}.
|
|
@end deftypefun
|
|
|
|
@deftypefun mp_size mpn_rshiftci (mp_ptr @var{dest_ptr}, mp_srcptr @var{src_ptr}, mp_size @var{src_size}, unsigned long int @var{count}, mp_limb @var{inlimb})
|
|
Like mpn_rshift, but use @var{inlimb} to feed the least significant end
|
|
of the destination.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mpn_cmp (mp_srcptr @var{src1_ptr}, mp_srcptr @var{src2_ptr}, mp_size @var{size})
|
|
Compare @{@var{src1_ptr}, @var{size}@} and @{@var{src2_ptr}, @var{size}@}
|
|
and return a positive value if src1 > src2, 0 of they are equal,
|
|
and a negative value if src1 < src2.
|
|
@end deftypefun
|
|
|
|
|
|
@node BSD Compatible Functions, Miscellaneous Functions, Low-level Functions, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Berkeley MP Compatible Functions
|
|
@cindex BSD MP compatible functions
|
|
|
|
These functions are intended to be fully compatible with the Berkeley MP
|
|
library which is available on many BSD derived U*ix systems.
|
|
|
|
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 compatible functions in GNU MP do not share this
|
|
restriction---inputs and outputs may overlap.
|
|
|
|
It is not recommended that new programs are written using these
|
|
functions. Apart from the incomplete set of functions, the interface
|
|
for initializing @code{MINT} objects is more error prone, and the
|
|
@code{pow} function collides with @code{pow} in @file{libm.a}.
|
|
|
|
Include the header @file{mp.h} to get the definition of the necessary
|
|
types and functions. If you are on a BSD derived system, make sure to
|
|
include GNU @file{mp.h} if you are going to link the GNU @file{libmp.a}
|
|
to you program. 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}.
|
|
|
|
@deftypefun {MINT *} itom (signed short int @var{initial_value})
|
|
Allocate an integer consisting of a @code{MINT} object and dynamic limb
|
|
space. Initialize the integer to @var{initial_value}. Return a pointer
|
|
to the @code{MINT} object.
|
|
@end deftypefun
|
|
|
|
@deftypefun {MINT *} xtom (char *@var{initial_value})
|
|
Allocate an integer consisting of a @code{MINT} object and dynamic limb
|
|
space. Initialize the integer from @var{initial_value}, a hexadecimal,
|
|
'\0'-terminate C string. Return a pointer to the @code{MINT} object.
|
|
@end deftypefun
|
|
|
|
@deftypefun void move (MINT *@var{src}, MINT *@var{dest})
|
|
Set @var{dest} to @var{src} by copying. Both variables must be
|
|
previously initialized.
|
|
@end deftypefun
|
|
|
|
@deftypefun void madd (MINT *@var{src_1}, MINT *@var{src_2}, MINT *@var{destination})
|
|
Add @var{src_1} and @var{src_2} and put the sum in @var{destination}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void msub (MINT *@var{src_1}, MINT *@var{src_2}, MINT *@var{destination})
|
|
Subtract @var{src_2} from @var{src_1} and put the difference in
|
|
@var{destination}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mult (MINT *@var{src_1}, MINT *@var{src_2}, MINT *@var{destination})
|
|
Multiply @var{src_1} and @var{src_2} and put the product in
|
|
@var{destination}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mdiv (MINT *@var{dividend}, MINT *@var{divisor}, MINT *@var{quotient}, MINT *@var{remainder})
|
|
@end deftypefun
|
|
@deftypefun void sdiv (MINT *@var{dividend}, signed short int @var{divisor}, MINT *@var{quotient}, signed short int *@var{remainder})
|
|
Set @var{quotient} to @var{dividend} / @var{divisor}, and
|
|
@var{remainder} to @var{dividend} mod @var{divisor}. The quotient is
|
|
rounded towards zero; the remainder has the same sign as the dividend.
|
|
|
|
Some implementations of this function return a remainder whose sign is
|
|
inverted if the divisor is negative. Such a definition makes little
|
|
sense from a mathematical point of view. GNU MP might be considered
|
|
incompatible with the traditional MP in this respect.
|
|
@end deftypefun
|
|
|
|
@deftypefun void msqrt (MINT *@var{operand}, MINT *@var{root}, MINT *@var{remainder})
|
|
Set @var{root} to the square root of @var{operand}, as with
|
|
@code{mpz_sqrt}. Set @var{remainder} to
|
|
@ifinfo
|
|
@var{operand}-@var{root}*@var{root},
|
|
@end ifinfo
|
|
@iftex
|
|
@tex
|
|
$operand - root^2$,
|
|
@end tex
|
|
@end iftex
|
|
(i.e@. zero if @var{operand} is a perfect square).
|
|
@end deftypefun
|
|
|
|
@deftypefun void pow (MINT *@var{base}, MINT *@var{exp}, MINT *@var{mod}, MINT *@var{dest})
|
|
Set @var{dest} to (@var{base} raised to @var{exp}) modulo @var{mod}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void rpow (MINT *@var{base}, signed short int @var{exp}, MINT *@var{dest})
|
|
Set @var{dest} to @var{base} raised to @var{exp}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void gcd (MINT *@var{operand1}, MINT *@var{operand2}, MINT *@var{res})
|
|
Set @var{res} to the greatest common divisor of @var{operand1} and
|
|
@var{operand2}.
|
|
@end deftypefun
|
|
|
|
@deftypefun int mcmp (MINT *@var{operand1}, MINT *@var{operand2})
|
|
Compare @var{operand1} and @var{operand2}. Return a positive value if
|
|
@var{operand1} > @var{operand2}, zero if @var{operand1} =
|
|
@var{operand2}, and a negative value if @var{operand1} < @var{operand2}.
|
|
@end deftypefun
|
|
|
|
@deftypefun void min (MINT *@var{dest})
|
|
Input a decimal string from stdin, and put the read integer in
|
|
@var{dest}. SPC and TAB are allowed in the number string, and are
|
|
ignored.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mout (MINT *@var{src})
|
|
Output @var{src} to stdout, as a decimal string. Also output a newline.
|
|
@end deftypefun
|
|
|
|
@deftypefun {char *} mtox (MINT *@var{operand})
|
|
Convert @var{operand} to a hexadecimal string, and return a pointer to
|
|
the string. The returned string is allocated using the default memory
|
|
allocation function, @code{malloc} by default. (@xref{Initialization},
|
|
for an explanation of the memory allocation in MP).
|
|
@end deftypefun
|
|
|
|
@deftypefun void mfree (MINT *@var{operand})
|
|
De-allocate, the space used by @var{operand}. @strong{This function
|
|
should only be passed a value returned by @code{itom} or @code{xtom}.}
|
|
@end deftypefun
|
|
|
|
@node Miscellaneous Functions, Custom Allocation, BSD Compatible Functions, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Miscellaneous Functions
|
|
@cindex Miscellaneous functions
|
|
|
|
@deftypefun void mpz_random (MP_INT *@var{random_integer}, mp_size @var{max_size})
|
|
Generate a random integer of at most @var{max_size} limbs. The generated
|
|
random number doesn't satisfy any particular requirements of randomness.
|
|
@end deftypefun
|
|
|
|
@deftypefun void mpz_random2 (MP_INT *@var{random_integer}, mp_size @var{max_size})
|
|
Generate a random integer of at most @var{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 bugs.
|
|
@end deftypefun
|
|
|
|
@deftypefun size_t mpz_size (MP_INT *@var{integer})
|
|
Return the size of @var{integer} measured in number of limbs. If
|
|
@var{integer} is zero, the returned value will be zero, if @var{integer}
|
|
has one limb, the returned value will be one, etc.
|
|
(@xref{Nomenclature}, for an explanation of the concept @dfn{limb}.)
|
|
@end deftypefun
|
|
|
|
@deftypefun size_t mpz_sizeinbase (MP_INT *@var{integer}, int @var{base})
|
|
Return the size of @var{integer} measured in number of digits in base
|
|
@var{base}. The base may vary from 2 to 36. The returned value will be
|
|
exact or 1 too big. If @var{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 @var{integer} to a string. The right amount of
|
|
allocation is normally two more than the value returned by
|
|
@code{mpz_sizeinbase} (one extra for a minus sign and one for the
|
|
terminating '\0').
|
|
@end deftypefun
|
|
|
|
@node Custom Allocation, Reporting Bugs, Miscellaneous Functions, Top
|
|
@comment node-name, next, previous, up
|
|
@section Custom Allocation
|
|
|
|
By default, the initialization functions use @code{malloc},
|
|
@code{realloc}, and @code{free} to do their work. If @code{malloc} or
|
|
@code{realloc} fails, the MP package terminates execution after a
|
|
printing fatal error message on standard error.
|
|
|
|
In some applications, you may wish to allocate memory in other ways, or
|
|
you may not want to have a fatal error when there is no more memory
|
|
available. To accomplish this, you can specify alternative functions
|
|
for allocating and de-allocating memory. Use
|
|
@code{mp_set_memory_functions} to do this.
|
|
|
|
@findex mp_set_memory_functions
|
|
@code{mp_set_memory_functions} has three arguments,
|
|
@var{allocate_function}, @var{reallocate_function}, and
|
|
@var{deallocate_function}, in that order. If an argument is NULL,
|
|
the corresponding default function is retained.
|
|
|
|
The functions you supply should fit the following declarations:
|
|
|
|
@table @code
|
|
@item void * @var{allocate_function} (size_t @var{alloc_size})
|
|
This function should return a pointer to newly allocated space with at
|
|
least @var{alloc_size} storage units.
|
|
|
|
@item void * @var{reallocate_function} (void *@var{ptr}, size_t @var{old_size}, size_t @var{new_size})
|
|
This function should return a pointer to newly allocated space of at
|
|
least @var{new_size} storage units, after copying the first
|
|
@var{old_size} storage units from @var{ptr}. It should also de-allocate the
|
|
space at @var{ptr}.
|
|
|
|
You can assume that the space at @var{ptr} was formely returned from
|
|
@var{allocate_function} or @var{reallocate_function}, for a
|
|
request for @var{old_size} storage units.
|
|
|
|
@item void @var{deallocate_function} (void *@var{ptr}, size_t @var{size})
|
|
De-allocate the space pointed to by @var{ptr}.
|
|
|
|
You can assume that the space at @var{ptr} was formely returned from
|
|
@var{allocate_function} or @var{reallocate_function}, for a
|
|
request for @var{size} storage units.
|
|
@end table
|
|
|
|
(A @dfn{storage unit} is the unit in which the @code{sizeof} operator
|
|
returns the size of an object, normally an 8 bit byte.)
|
|
|
|
@strong{NOTE: call @code{mp_set_memory_functions} only before calling
|
|
any other MP functions.} Otherwise, the user-defined allocation
|
|
functions may be asked to re-allocate or de-allocate something
|
|
previously allocated by the default allocation functions.
|
|
|
|
@node Reporting Bugs, , Custom Allocation, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Reporting Bugs
|
|
@cindex Reporting bugs
|
|
|
|
If you think you have found a bug in the GNU 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.
|
|
|
|
Please make sure that the bug is really in the GNU MP library.
|
|
|
|
You have to send us a test case that makes it possible for us to
|
|
reproduce the bug.
|
|
|
|
You also have to explain what is wrong; if you get a crash, or if the
|
|
results printed are not good and in that case, in what way.
|
|
|
|
Make sure that the bug report includes all information you would
|
|
need to fix this kind of bug for someone else. Think twice.
|
|
|
|
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: tege@@gnu.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.
|
|
|
|
|
|
@node References, , , Top
|
|
@comment node-name, next, previous, up
|
|
@unnumbered References
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
Donald E@. Knuth, "The Art of Computer Programming", vol 2,
|
|
"Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981.
|
|
|
|
@item
|
|
John D@. Lipson, "Elements of Algebra and Algebraic Computing",
|
|
The Benjamin Cummins Publishing Company Inc, 1981.
|
|
|
|
@item
|
|
Richard M@. Stallman, "Using and Porting GCC", Free Software Foundation,
|
|
1993.
|
|
|
|
@item
|
|
Peter L@. Montgomery, "Modular Multiplication Without Trial Division",
|
|
Mathematics of Computation, volume 44, number 170, April 1985.
|
|
|
|
@end itemize
|
|
|
|
@node Concept Index, , , Top
|
|
@comment node-name, next, previous, up
|
|
@unnumbered Concept Index
|
|
@printindex cp
|
|
|
|
@node Function Index, , , Top
|
|
@comment node-name, next, previous, up
|
|
@unnumbered Function and Type Index
|
|
@printindex fn
|
|
|
|
|
|
@contents
|
|
@bye
|