Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libmpz.tex @ 4566:6403c94de50d legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added safeguard against failure in __del__.
author Guido van Rossum <guido@python.org>
date Wed, 27 Nov 1996 19:39:58 +0000
parents c0997b462344
children 3468ea8645ca
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
1 \section{Built-in Module \sectcode{mpz}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
2 \bimodindex{mpz}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3
2944
c0997b462344 clarify optional status
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
4 This is an optional module. It is only available when Python is
c0997b462344 clarify optional status
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
5 configured to include it, which requires that the GNU MP software is
c0997b462344 clarify optional status
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
6 installed.
c0997b462344 clarify optional status
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
7
c0997b462344 clarify optional status
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
8 This module implements the interface to part of the GNU MP library,
c0997b462344 clarify optional status
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
9 which defines arbitrary precision integer and rational number
c0997b462344 clarify optional status
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
10 arithmetic routines. Only the interfaces to the \emph{integer}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 (\samp{mpz_{\rm \ldots}}) routines are provided. If not stated
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 otherwise, the description in the GNU MP documentation can be applied.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 In general, \dfn{mpz}-numbers can be used just like other standard
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
15 Python numbers, e.g.\ you can use the built-in operators like \code{+},
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 \code{*}, etc., as well as the standard built-in functions like
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 \code{abs}, \code{int}, \ldots, \code{divmod}, \code{pow}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 \strong{Please note:} the {\it bitwise-xor} operation has been implemented as
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 a bunch of {\it and}s, {\it invert}s and {\it or}s, because the library
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 lacks an \code{mpz_xor} function, and I didn't need one.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
22 You create an mpz-number by calling the function called \code{mpz} (see
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
23 below for an exact description). An mpz-number is printed like this:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 \code{mpz(\var{value})}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 \renewcommand{\indexsubitem}{(in module mpz)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \begin{funcdesc}{mpz}{value}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 Create a new mpz-number. \var{value} can be an integer, a long,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 another mpz-number, or even a string. If it is a string, it is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 interpreted as an array of radix-256 digits, least significant digit
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 first, resulting in a positive number. See also the \code{binary}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 method, described below.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 A number of {\em extra} functions are defined in this module. Non
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 mpz-arguments are converted to mpz-values first, and the functions
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 return mpz-numbers.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 \begin{funcdesc}{powm}{base\, exponent\, modulus}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 Return \code{pow(\var{base}, \var{exponent}) \%{} \var{modulus}}. If
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 \code{\var{exponent} == 0}, return \code{mpz(1)}. In contrast to the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
42 \C-library function, this version can handle negative exponents.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 \begin{funcdesc}{gcd}{op1\, op2}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 Return the greatest common divisor of \var{op1} and \var{op2}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 \begin{funcdesc}{gcdext}{a\, b}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 Return a tuple \code{(\var{g}, \var{s}, \var{t})}, such that
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 \code{\var{a}*\var{s} + \var{b}*\var{t} == \var{g} == gcd(\var{a}, \var{b})}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 \begin{funcdesc}{sqrt}{op}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 Return the square root of \var{op}. The result is rounded towards zero.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
57
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 \begin{funcdesc}{sqrtrem}{op}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 Return a tuple \code{(\var{root}, \var{remainder})}, such that
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 \code{\var{root}*\var{root} + \var{remainder} == \var{op}}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
62
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 \begin{funcdesc}{divm}{numerator\, denominator\, modulus}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 Returns a number \var{q}. such that
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 \code{\var{q} * \var{denominator} \%{} \var{modulus} == \var{numerator}}.
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
66 One could also implement this function in Python, using \code{gcdext}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
68
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 An mpz-number has one method:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
70
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 \renewcommand{\indexsubitem}{(mpz method)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 \begin{funcdesc}{binary}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 Convert this mpz-number to a binary string, where the number has been
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 stored as an array of radix-256 digits, least significant digit first.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
75
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
76 The mpz-number must have a value greater than or equal to zero,
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 otherwise a \code{ValueError}-exception will be raised.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 \end{funcdesc}