home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / pyhtmldoc / m / mpz < prev    next >
Text File  |  1996-11-14  |  4KB  |  73 lines
  1. <TITLE>mpz -- Python library reference</TITLE>
  2. Next: <A HREF="../r/rotor" TYPE="Next">rotor</A>  
  3. Prev: <A HREF="../m/md5" TYPE="Prev">md5</A>  
  4. Up: <A HREF="../c/cryptographic_services" TYPE="Up">Cryptographic Services</A>  
  5. Top: <A HREF="../t/top" TYPE="Top">Top</A>  
  6. <H1>12.2. Built-in Module <CODE>mpz</CODE></H1>
  7. This is an optional module.  It is only available when Python is
  8. configured to include it, which requires that the GNU MP software is
  9. installed.
  10. <P>
  11. This module implements the interface to part of the GNU MP library,
  12. which defines arbitrary precision integer and rational number
  13. arithmetic routines.  Only the interfaces to the <I>integer</I>
  14. (`<SAMP>mpz_<R>...</R></SAMP>') routines are provided. If not stated
  15. otherwise, the description in the GNU MP documentation can be applied.
  16. <P>
  17. In general, <DFN>mpz</DFN>-numbers can be used just like other standard
  18. Python numbers, e.g. you can use the built-in operators like <CODE>+</CODE>,
  19. <CODE>*</CODE>, etc., as well as the standard built-in functions like
  20. <CODE>abs</CODE>, <CODE>int</CODE>, ..., <CODE>divmod</CODE>, <CODE>pow</CODE>.
  21. <B>Please note:</B> the <I>bitwise-xor</I> operation has been implemented as
  22. a bunch of <I>and</I>s, <I>invert</I>s and <I>or</I>s, because the library
  23. lacks an <CODE>mpz_xor</CODE> function, and I didn't need one.
  24. <P>
  25. You create an mpz-number by calling the function called <CODE>mpz</CODE> (see
  26. below for an exact description). An mpz-number is printed like this:
  27. <CODE>mpz(<VAR>value</VAR>)</CODE>.
  28. <P>
  29. <DL><DT><B>mpz</B> (<VAR>value</VAR>) -- function of module mpz<DD>
  30. Create a new mpz-number. <VAR>value</VAR> can be an integer, a long,
  31. another mpz-number, or even a string. If it is a string, it is
  32. interpreted as an array of radix-256 digits, least significant digit
  33. first, resulting in a positive number. See also the <CODE>binary</CODE>
  34. method, described below.
  35. </DL>
  36. A number of <I>extra</I> functions are defined in this module. Non
  37. mpz-arguments are converted to mpz-values first, and the functions
  38. return mpz-numbers.
  39. <P>
  40. <DL><DT><B>powm</B> (<VAR>base</VAR>, <VAR>exponent</VAR>, <VAR>modulus</VAR>) -- function of module mpz<DD>
  41. Return <CODE>pow(<VAR>base</VAR>, <VAR>exponent</VAR>) % <VAR>modulus</VAR></CODE>. If
  42. <CODE><VAR>exponent</VAR> == 0</CODE>, return <CODE>mpz(1)</CODE>. In contrast to the
  43. C-library function, this version can handle negative exponents.
  44. </DL>
  45. <DL><DT><B>gcd</B> (<VAR>op1</VAR>, <VAR>op2</VAR>) -- function of module mpz<DD>
  46. Return the greatest common divisor of <VAR>op1</VAR> and <VAR>op2</VAR>.
  47. </DL>
  48. <DL><DT><B>gcdext</B> (<VAR>a</VAR>, <VAR>b</VAR>) -- function of module mpz<DD>
  49. Return a tuple <CODE>(<VAR>g</VAR>, <VAR>s</VAR>, <VAR>t</VAR>)</CODE>, such that
  50. <CODE><VAR>a</VAR>*<VAR>s</VAR> + <VAR>b</VAR>*<VAR>t</VAR> == <VAR>g</VAR> == gcd(<VAR>a</VAR>, <VAR>b</VAR>)</CODE>.
  51. </DL>
  52. <DL><DT><B>sqrt</B> (<VAR>op</VAR>) -- function of module mpz<DD>
  53. Return the square root of <VAR>op</VAR>. The result is rounded towards zero.
  54. </DL>
  55. <DL><DT><B>sqrtrem</B> (<VAR>op</VAR>) -- function of module mpz<DD>
  56. Return a tuple <CODE>(<VAR>root</VAR>, <VAR>remainder</VAR>)</CODE>, such that
  57. <CODE><VAR>root</VAR>*<VAR>root</VAR> + <VAR>remainder</VAR> == <VAR>op</VAR></CODE>.
  58. </DL>
  59. <DL><DT><B>divm</B> (<VAR>numerator</VAR>, <VAR>denominator</VAR>, <VAR>modulus</VAR>) -- function of module mpz<DD>
  60. Returns a number <VAR>q</VAR>. such that
  61. <CODE><VAR>q</VAR> * <VAR>denominator</VAR> % <VAR>modulus</VAR> == <VAR>numerator</VAR></CODE>.
  62. One could also implement this function in Python, using <CODE>gcdext</CODE>.
  63. </DL>
  64. An mpz-number has one method:
  65. <P>
  66. <DL><DT><B>binary</B> () -- Method on mpz<DD>
  67. Convert this mpz-number to a binary string, where the number has been
  68. stored as an array of radix-256 digits, least significant digit first.
  69. <P>
  70. The mpz-number must have a value greater than or equal to zero,
  71. otherwise a <CODE>ValueError</CODE>-exception will be raised.
  72. </DL>
  73.