1 \section{\module{mpz
} ---
2 GNU arbitrary magnitude integers
}
4 \declaremodule{builtin
}{mpz
}
5 \modulesynopsis{Interface to the GNU MP library for arbitrary
9 This is an optional module. It is only available when Python is
10 configured to include it, which requires that the GNU MP software is
12 \index{MP, GNU library
}
13 \index{arbitrary precision integers
}
14 \index{integer!arbitrary precision
}
16 This module implements the interface to part of the GNU MP library,
17 which defines arbitrary precision integer and rational number
18 arithmetic routines. Only the interfaces to the
\emph{integer
}
19 (
\function{mpz_*()
}) routines are provided. If not stated
20 otherwise, the description in the GNU MP documentation can be applied.
22 Support for rational numbers
\index{rational numbers
} can be
23 implemented in Python. For an example, see the
24 \module{Rat
}\withsubitem{(demo module)
}{\ttindex{Rat
}} module, provided as
25 \file{Demos/classes/Rat.py
} in the Python source distribution.
27 In general,
\dfn{mpz
}-numbers can be used just like other standard
28 Python numbers, e.g., you can use the built-in operators like
\code{+
},
29 \code{*
}, etc., as well as the standard built-in functions like
30 \function{abs()
},
\function{int()
},
\ldots,
\function{divmod()
},
31 \function{pow()
}.
\strong{Please note:
} the
\emph{bitwise-xor
}
32 operation has been implemented as a bunch of
\emph{and
}s,
33 \emph{invert
}s and
\emph{or
}s, because the library lacks an
34 \cfunction{mpz_xor()
} function, and I didn't need one.
36 You create an mpz-number by calling the function
\function{mpz()
} (see
37 below for an exact description). An mpz-number is printed like this:
38 \code{mpz(
\var{value
})
}.
41 \begin{funcdesc
}{mpz
}{value
}
42 Create a new mpz-number.
\var{value
} can be an integer, a long,
43 another mpz-number, or even a string. If it is a string, it is
44 interpreted as an array of radix-
256 digits, least significant digit
45 first, resulting in a positive number. See also the
\method{binary()
}
46 method, described below.
49 \begin{datadesc
}{MPZType
}
50 The type of the objects returned by
\function{mpz()
} and most other
51 functions in this module.
55 A number of
\emph{extra
} functions are defined in this module. Non
56 mpz-arguments are converted to mpz-values first, and the functions
59 \begin{funcdesc
}{powm
}{base, exponent, modulus
}
60 Return
\code{pow(
\var{base
},
\var{exponent
}) \%
{} \var{modulus
}}. If
61 \code{\var{exponent
} ==
0}, return
\code{mpz(
1)
}. In contrast to the
62 \C{} library function, this version can handle negative exponents.
65 \begin{funcdesc
}{gcd
}{op1, op2
}
66 Return the greatest common divisor of
\var{op1
} and
\var{op2
}.
69 \begin{funcdesc
}{gcdext
}{a, b
}
70 Return a tuple
\code{(
\var{g
},
\var{s
},
\var{t
})
}, such that
71 \code{\var{a
}*
\var{s
} +
\var{b
}*
\var{t
} ==
\var{g
} == gcd(
\var{a
},
\var{b
})
}.
74 \begin{funcdesc
}{sqrt
}{op
}
75 Return the square root of
\var{op
}. The result is rounded towards zero.
78 \begin{funcdesc
}{sqrtrem
}{op
}
79 Return a tuple
\code{(
\var{root
},
\var{remainder
})
}, such that
80 \code{\var{root
}*
\var{root
} +
\var{remainder
} ==
\var{op
}}.
83 \begin{funcdesc
}{divm
}{numerator, denominator, modulus
}
84 Returns a number
\var{q
} such that
85 \code{\var{q
} *
\var{denominator
} \%
{} \var{modulus
} ==
86 \var{numerator
}}. One could also implement this function in Python,
87 using
\function{gcdext()
}.
90 An mpz-number has one method:
92 \begin{methoddesc
}[mpz
]{binary
}{}
93 Convert this mpz-number to a binary string, where the number has been
94 stored as an array of radix-
256 digits, least significant digit first.
96 The mpz-number must have a value greater than or equal to zero,
97 otherwise
\exception{ValueError
} will be raised.
