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