Doc/lib/libmpz.tex

   1 \section{Built-in Module \sectcode{mpz}}
   2 \bimodindex{mpz}
   3
   4 This is an optional module.  It is only available when Python is
   5 configured to include it, which requires that the GNU MP software is
   6 installed.
   7
   8 This module implements the interface to part of the GNU MP library,
   9 which defines arbitrary precision integer and rational number
  10 arithmetic routines.  Only the interfaces to the \emph{integer}
  11 (\samp{mpz_{\rm \ldots}}) routines are provided. If not stated
  12 otherwise, the description in the GNU MP documentation can be applied.
  13
  14 In general, \dfn{mpz}-numbers can be used just like other standard
  15 Python numbers, e.g.\ you can use the built-in operators like \code{+},
  16 \code{*}, etc., as well as the standard built-in functions like
  17 \code{abs}, \code{int}, \ldots, \code{divmod}, \code{pow}.
  18 \strong{Please note:} the {\it bitwise-xor} operation has been implemented as
  19 a bunch of {\it and}s, {\it invert}s and {\it or}s, because the library
  20 lacks an \code{mpz_xor} function, and I didn't need one.
  21
  22 You create an mpz-number by calling the function called \code{mpz} (see
  23 below for an exact description). An mpz-number is printed like this:
  24 \code{mpz(\var{value})}.
  25
  26 \renewcommand{\indexsubitem}{(in module mpz)}
  27 \begin{funcdesc}{mpz}{value}
  28   Create a new mpz-number. \var{value} can be an integer, a long,
  29   another mpz-number, or even a string. If it is a string, it is
  30   interpreted as an array of radix-256 digits, least significant digit
  31   first, resulting in a positive number. See also the \code{binary}
  32   method, described below.
  33 \end{funcdesc}
  34
  35 A number of {\em extra} functions are defined in this module. Non
  36 mpz-arguments are converted to mpz-values first, and the functions
  37 return mpz-numbers.
  38
  39 \begin{funcdesc}{powm}{base\, exponent\, modulus}
  40   Return \code{pow(\var{base}, \var{exponent}) \%{} \var{modulus}}. If
  41   \code{\var{exponent} == 0}, return \code{mpz(1)}. In contrast to the
  42   \C-library function, this version can handle negative exponents.
  43 \end{funcdesc}
  44
  45 \begin{funcdesc}{gcd}{op1\, op2}
  46   Return the greatest common divisor of \var{op1} and \var{op2}.
  47 \end{funcdesc}
  48
  49 \begin{funcdesc}{gcdext}{a\, b}
  50   Return a tuple \code{(\var{g}, \var{s}, \var{t})}, such that
  51   \code{\var{a}*\var{s} + \var{b}*\var{t} == \var{g} == gcd(\var{a}, \var{b})}.
  52 \end{funcdesc}
  53
  54 \begin{funcdesc}{sqrt}{op}
  55   Return the square root of \var{op}. The result is rounded towards zero.
  56 \end{funcdesc}
  57
  58 \begin{funcdesc}{sqrtrem}{op}
  59   Return a tuple \code{(\var{root}, \var{remainder})}, such that
  60   \code{\var{root}*\var{root} + \var{remainder} == \var{op}}.
  61 \end{funcdesc}
  62
  63 \begin{funcdesc}{divm}{numerator\, denominator\, modulus}
  64   Returns a number \var{q}. such that
  65   \code{\var{q} * \var{denominator} \%{} \var{modulus} == \var{numerator}}.
  66   One could also implement this function in Python, using \code{gcdext}.
  67 \end{funcdesc}
  68
  69 An mpz-number has one method:
  70
  71 \renewcommand{\indexsubitem}{(mpz method)}
  72 \begin{funcdesc}{binary}{}
  73   Convert this mpz-number to a binary string, where the number has been
  74   stored as an array of radix-256 digits, least significant digit first.
  75
  76   The mpz-number must have a value greater than or equal to zero,
  77   otherwise a \code{ValueError}-exception will be raised.
  78 \end{funcdesc}