\section{\module{mpz} --- GNU arbitrary magnitude integers} \declaremodule{builtin}{mpz} \modulesynopsis{Interface to the GNU MP library for arbitrary precision arithmetic.} 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}