Doc/lib/libmpz.tex

   1 \section{\module{mpz} ---
   2          GNU arbitrary magnitude integers}
   3
   4 \declaremodule{builtin}{mpz}
   5 \modulesynopsis{Interface to the GNU MP library for arbitrary
   6 precision arithmetic.}
   7
   8
   9 \deprecated{2.2}{See the references at the end of this section for
  10                  information about packages which provide similar
  11                  functionality.  This module will be removed in Python
  12                  2.3.}
  13
  14
  15 This is an optional module.  It is only available when Python is
  16 configured to include it, which requires that the GNU MP software is
  17 installed.
  18 \index{MP, GNU library}
  19 \index{arbitrary precision integers}
  20 \index{integer!arbitrary precision}
  21
  22 This module implements the interface to part of the GNU MP library,
  23 which defines arbitrary precision integer and rational number
  24 arithmetic routines.  Only the interfaces to the \emph{integer}
  25 (\function{mpz_*()}) routines are provided. If not stated
  26 otherwise, the description in the GNU MP documentation can be applied.
  27
  28 Support for rational numbers\index{rational numbers} can be
  29 implemented in Python.  For an example, see the
  30 \module{Rat}\withsubitem{(demo module)}{\ttindex{Rat}} module, provided as
  31 \file{Demos/classes/Rat.py} in the Python source distribution.
  32
  33 In general, \dfn{mpz}-numbers can be used just like other standard
  34 Python numbers, e.g., you can use the built-in operators like \code{+},
  35 \code{*}, etc., as well as the standard built-in functions like
  36 \function{abs()}, \function{int()}, \ldots, \function{divmod()},
  37 \function{pow()}.  \strong{Please note:} the \emph{bitwise-xor}
  38 operation has been implemented as a bunch of \emph{and}s,
  39 \emph{invert}s and \emph{or}s, because the library lacks an
  40 \cfunction{mpz_xor()} function, and I didn't need one.
  41
  42 You create an mpz-number by calling the function \function{mpz()} (see
  43 below for an exact description). An mpz-number is printed like this:
  44 \code{mpz(\var{value})}.
  45
  46
  47 \begin{funcdesc}{mpz}{value}
  48   Create a new mpz-number. \var{value} can be an integer, a long,
  49   another mpz-number, or even a string. If it is a string, it is
  50   interpreted as an array of radix-256 digits, least significant digit
  51   first, resulting in a positive number. See also the \method{binary()}
  52   method, described below.
  53 \end{funcdesc}
  54
  55 \begin{datadesc}{MPZType}
  56   The type of the objects returned by \function{mpz()} and most other
  57   functions in this module.
  58 \end{datadesc}
  59
  60
  61 A number of \emph{extra} functions are defined in this module. Non
  62 mpz-arguments are converted to mpz-values first, and the functions
  63 return mpz-numbers.
  64
  65 \begin{funcdesc}{powm}{base, exponent, modulus}
  66   Return \code{pow(\var{base}, \var{exponent}) \%{} \var{modulus}}. If
  67   \code{\var{exponent} == 0}, return \code{mpz(1)}. In contrast to the
  68   \C{} library function, this version can handle negative exponents.
  69 \end{funcdesc}
  70
  71 \begin{funcdesc}{gcd}{op1, op2}
  72   Return the greatest common divisor of \var{op1} and \var{op2}.
  73 \end{funcdesc}
  74
  75 \begin{funcdesc}{gcdext}{a, b}
  76   Return a tuple \code{(\var{g}, \var{s}, \var{t})}, such that
  77   \code{\var{a}*\var{s} + \var{b}*\var{t} == \var{g} == gcd(\var{a}, \var{b})}.
  78 \end{funcdesc}
  79
  80 \begin{funcdesc}{sqrt}{op}
  81   Return the square root of \var{op}. The result is rounded towards zero.
  82 \end{funcdesc}
  83
  84 \begin{funcdesc}{sqrtrem}{op}
  85   Return a tuple \code{(\var{root}, \var{remainder})}, such that
  86   \code{\var{root}*\var{root} + \var{remainder} == \var{op}}.
  87 \end{funcdesc}
  88
  89 \begin{funcdesc}{divm}{numerator, denominator, modulus}
  90   Returns a number \var{q} such that
  91   \code{\var{q} * \var{denominator} \%{} \var{modulus} ==
  92   \var{numerator}}.  One could also implement this function in Python,
  93   using \function{gcdext()}.
  94 \end{funcdesc}
  95
  96 An mpz-number has one method:
  97
  98 \begin{methoddesc}[mpz]{binary}{}
  99   Convert this mpz-number to a binary string, where the number has been
 100   stored as an array of radix-256 digits, least significant digit first.
 101
 102   The mpz-number must have a value greater than or equal to zero,
 103   otherwise \exception{ValueError} will be raised.
 104 \end{methoddesc}
 105
 106
 107 \begin{seealso}
 108   \seetitle[http://gmpy.sourceforge.net/]{General Multiprecision Python}{
 109             This project is building new numeric types to allow
 110             arbitrary-precision arithmetic in Python.  Their first
 111             efforts are also based on the GNU MP library.}
 112
 113   \seetitle[http://www.egenix.com/files/python/mxNumber.html]{mxNumber
 114             --- Extended Numeric Types for Python}{Another wrapper
 115             around the GNU MP library, including a port of that
 116             library to Windows.}
 117 \end{seealso}