mirror of
https://github.com/python/cpython.git
synced 2025-11-04 03:44:55 +00:00
117 lines
4.4 KiB
TeX
117 lines
4.4 KiB
TeX
\section{\module{mpz} ---
|
|
GNU arbitrary magnitude integers}
|
|
|
|
\declaremodule{builtin}{mpz}
|
|
\modulesynopsis{Interface to the GNU MP library for arbitrary
|
|
precision arithmetic.}
|
|
|
|
|
|
\deprecated{2.2}{See the references at the end of this section for
|
|
information about packages which provide similar
|
|
functionality. This module will be removed in Python
|
|
2.3.}
|
|
|
|
|
|
This is an optional module. It is only available when Python is
|
|
configured to include it, which requires that the GNU MP software is
|
|
installed.
|
|
\index{MP, GNU library}
|
|
\index{arbitrary precision integers}
|
|
\index{integer!arbitrary precision}
|
|
|
|
This module implements the interface to part of the GNU MP library,
|
|
which defines arbitrary precision integer and rational number
|
|
arithmetic routines. Only the interfaces to the \emph{integer}
|
|
(\function{mpz_*()}) routines are provided. If not stated
|
|
otherwise, the description in the GNU MP documentation can be applied.
|
|
|
|
Support for rational numbers\index{rational numbers} can be
|
|
implemented in Python. For an example, see the
|
|
\module{Rat}\withsubitem{(demo module)}{\ttindex{Rat}} module, provided as
|
|
\file{Demos/classes/Rat.py} in the Python source distribution.
|
|
|
|
In general, \dfn{mpz}-numbers can be used just like other standard
|
|
Python numbers, e.g., you can use the built-in operators like \code{+},
|
|
\code{*}, etc., as well as the standard built-in functions like
|
|
\function{abs()}, \function{int()}, \ldots, \function{divmod()},
|
|
\function{pow()}. \strong{Please note:} the \emph{bitwise-xor}
|
|
operation has been implemented as a bunch of \emph{and}s,
|
|
\emph{invert}s and \emph{or}s, because the library lacks an
|
|
\cfunction{mpz_xor()} function, and I didn't need one.
|
|
|
|
You create an mpz-number by calling the function \function{mpz()} (see
|
|
below for an exact description). An mpz-number is printed like this:
|
|
\code{mpz(\var{value})}.
|
|
|
|
|
|
\begin{funcdesc}{mpz}{value}
|
|
Create a new mpz-number. \var{value} can be an integer, a long,
|
|
another mpz-number, or even a string. If it is a string, it is
|
|
interpreted as an array of radix-256 digits, least significant digit
|
|
first, resulting in a positive number. See also the \method{binary()}
|
|
method, described below.
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{MPZType}
|
|
The type of the objects returned by \function{mpz()} and most other
|
|
functions in this module.
|
|
\end{datadesc}
|
|
|
|
|
|
A number of \emph{extra} functions are defined in this module. Non
|
|
mpz-arguments are converted to mpz-values first, and the functions
|
|
return mpz-numbers.
|
|
|
|
\begin{funcdesc}{powm}{base, exponent, modulus}
|
|
Return \code{pow(\var{base}, \var{exponent}) \%{} \var{modulus}}. If
|
|
\code{\var{exponent} == 0}, return \code{mpz(1)}. In contrast to the
|
|
\C{} library function, this version can handle negative exponents.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{gcd}{op1, op2}
|
|
Return the greatest common divisor of \var{op1} and \var{op2}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{gcdext}{a, b}
|
|
Return a tuple \code{(\var{g}, \var{s}, \var{t})}, such that
|
|
\code{\var{a}*\var{s} + \var{b}*\var{t} == \var{g} == gcd(\var{a}, \var{b})}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sqrt}{op}
|
|
Return the square root of \var{op}. The result is rounded towards zero.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sqrtrem}{op}
|
|
Return a tuple \code{(\var{root}, \var{remainder})}, such that
|
|
\code{\var{root}*\var{root} + \var{remainder} == \var{op}}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{divm}{numerator, denominator, modulus}
|
|
Returns a number \var{q} such that
|
|
\code{\var{q} * \var{denominator} \%{} \var{modulus} ==
|
|
\var{numerator}}. One could also implement this function in Python,
|
|
using \function{gcdext()}.
|
|
\end{funcdesc}
|
|
|
|
An mpz-number has one method:
|
|
|
|
\begin{methoddesc}[mpz]{binary}{}
|
|
Convert this mpz-number to a binary string, where the number has been
|
|
stored as an array of radix-256 digits, least significant digit first.
|
|
|
|
The mpz-number must have a value greater than or equal to zero,
|
|
otherwise \exception{ValueError} will be raised.
|
|
\end{methoddesc}
|
|
|
|
|
|
\begin{seealso}
|
|
\seetitle[http://gmpy.sourceforge.net/]{General Multiprecision Python}{
|
|
This project is building new numeric types to allow
|
|
arbitrary-precision arithmetic in Python. Their first
|
|
efforts are also based on the GNU MP library.}
|
|
|
|
\seetitle[http://www.egenix.com/files/python/mxNumber.html]{mxNumber
|
|
--- Extended Numeric Types for Python}{Another wrapper
|
|
around the GNU MP library, including a port of that
|
|
library to Windows.}
|
|
\end{seealso}
|