GNU Info

(python2.1-lib.info)mpz

---

Next: rotor Prev: sha Up: Cryptographic Services

---

Enter node , (file) or (file)node

GNU arbitrary magnitude integers
================================

Interface to the GNU MP library for arbitrary precision arithmetic.

This is an optional module.  It is only available when Python is
configured to include it, which requires that the GNU MP software is
installed.

This module implements the interface to part of the GNU MP library,
which defines arbitrary precision integer and rational number
arithmetic routines.  Only the interfaces to the _integer_ (`mpz_*()')
routines are provided. If not stated otherwise, the description in the
GNU MP documentation can be applied.

Support for rational numbers  can be implemented in Python.  For an
example, see the `Rat'  module, provided as `Demos/classes/Rat.py' in
the Python source distribution.

In general, "mpz"-numbers can be used just like other standard Python
numbers, e.g., you can use the built-in operators like `+', `*', etc.,
as well as the standard built-in functions like `abs()', `int()', ...,
`divmod()', `pow()'.  *Please note:* the _bitwise-xor_ operation has
been implemented as a bunch of _and_s, _invert_s and _or_s, because the
library lacks an `mpz_xor()' function, and I didn't need one.

You create an mpz-number by calling the function `mpz()' (see below for
an exact description). An mpz-number is printed like this: `mpz(VALUE)'.

`mpz(value)'
     Create a new mpz-number. VALUE can be an integer, a long, another
     mpz-number, or even a string. If it is a string, it is interpreted
     as an array of radix-256 digits, least significant digit first,
     resulting in a positive number. See also the `binary()' method,
     described below.

`MPZType'
     The type of the objects returned by `mpz()' and most other
     functions in this module.

A number of _extra_ functions are defined in this module. Non
mpz-arguments are converted to mpz-values first, and the functions
return mpz-numbers.

`powm(base, exponent, modulus)'
     Return `pow(BASE, EXPONENT) %{} MODULUS'. If `EXPONENT == 0',
     return `mpz(1)'. In contrast to the C library function, this
     version can handle negative exponents.

`gcd(op1, op2)'
     Return the greatest common divisor of OP1 and OP2.

`gcdext(a, b)'
     Return a tuple `(G, S, T)', such that `A*S + B*T == G == gcd(A,
     B)'.

`sqrt(op)'
     Return the square root of OP. The result is rounded towards zero.

`sqrtrem(op)'
     Return a tuple `(ROOT, REMAINDER)', such that `ROOT*ROOT +
     REMAINDER == OP'.

`divm(numerator, denominator, modulus)'
     Returns a number Q such that `Q * DENOMINATOR %{} MODULUS ==
     NUMERATOR'.  One could also implement this function in Python,
     using `gcdext()'.

An mpz-number has one method:

`binary()'
     Convert this mpz-number to a binary string, where the number has
     been stored as an array of radix-256 digits, least significant
     digit first.

     The mpz-number must have a value greater than or equal to zero,
     otherwise `ValueError' will be raised.

See also:
     `General Multiprecision Python'{ This project is building new
     numeric types to allow arbitrary-precision arithmetic in Python.
     Their first efforts are also based on the GNU MP library.}

     `mxNumber -- Extended Numeric Types for Python'{Another wrapper
     around the GNU MP library, including a port of that library to
     Windows.}