Restructured library documentation

1 files changed, 74 insertions, 0 deletions

diff --git a/Doc/libmpz.tex b/Doc/libmpz.tex
new file mode 100644
index 0000000..ea0d1b7
--- /dev/null
+++ b/Doc/libmpz.tex
@@ -0,0 +1,74 @@
+\section{Built-in module \sectcode{mpz}}
+\bimodindex{mpz}
+
+This module implements the interface to part of the GNU MP library.
+This library contains arbitrary precision integer and rational number
+arithmetic routines. Only the interfaces to the \emph{integer}
+(\samp{mpz_{\rm \ldots}}) routines are provided. If not stated
+otherwise, the description in the GNU MP documentation can be applied.
+
+In general, \dfn{mpz}-numbers can be used just like other standard
+Python numbers, e.g. you can use the built-in operators like \code{+},
+\code{*}, etc., as well as the standard built-in functions like
+\code{abs}, \code{int}, \ldots, \code{divmod}, \code{pow}.
+\strong{Please note:} the {\it bitwise-xor} operation has been implemented as
+a bunch of {\it and}s, {\it invert}s and {\it or}s, because the library
+lacks an \code{mpz_xor} function, and I didn't need one.
+
+You create an mpz-number, by calling the function called \code{mpz} (see
+below for an excact description). An mpz-number is printed like this:
+\code{mpz(\var{value})}.
+
+\renewcommand{\indexsubitem}{(in module mpz)}
+\begin{funcdesc}{mpz}{value}
+  Create a new mpz-number. \var{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 \code{binary}
+  method, described below.
+\end{funcdesc}
+
+A number of {\em extra} functions are defined in this module. Non
+mpz-arguments are converted to mpz-values first, and the functions
+return mpz-numbers.
+
+\begin{funcdesc}{powm}{base\, exponent\, modulus}
+  Return \code{pow(\var{base}, \var{exponent}) \%{} \var{modulus}}. If
+  \code{\var{exponent} == 0}, return \code{mpz(1)}. In contrast to the
+  \C-library function, this version can handle negative exponents.
+\end{funcdesc}
+
+\begin{funcdesc}{gcd}{op1\, op2}
+  Return the greatest common divisor of \var{op1} and \var{op2}.
+\end{funcdesc}
+
+\begin{funcdesc}{gcdext}{a\, b}
+  Return a tuple \code{(\var{g}, \var{s}, \var{t})}, such that
+  \code{\var{a}*\var{s} + \var{b}*\var{t} == \var{g} == gcd(\var{a}, \var{b})}.
+\end{funcdesc}
+
+\begin{funcdesc}{sqrt}{op}
+  Return the square root of \var{op}. The result is rounded towards zero.
+\end{funcdesc}
+
+\begin{funcdesc}{sqrtrem}{op}
+  Return a tuple \code{(\var{root}, \var{remainder})}, such that
+  \code{\var{root}*\var{root} + \var{remainder} == \var{op}}.
+\end{funcdesc}
+
+\begin{funcdesc}{divm}{numerator\, denominator\, modulus}
+  Returns a number \var{q}. such that
+  \code{\var{q} * \var{denominator} \%{} \var{modulus} == \var{numerator}}.
+  One could also implement this function in python, using \code{gcdext}.
+\end{funcdesc}
+
+An mpz-number has one method:
+
+\renewcommand{\indexsubitem}{(mpz method)}
+\begin{funcdesc}{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 a \code{ValueError}-exception will be raised.
+\end{funcdesc}