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