\fsec{Returns}
-The number of bytes occupied by an array of $n$ \code{mpw}s (i.e., $n \cdot
+The number of bytes occupied by an array of $n$~\code{mpw}s (i.e., $n \cdot
|sizeof(mpw)|$).
\subsubsection{The \code{MPW_RQ} macro}
\fsec{Returns}
The number of \code{mpw}s required to represent a multiprecision integer
-occupying $\sz$ octets in an external representation.
+occupying $\sz$~octets in an external representation.
\subsection{Low-level multiprecision integer representation}
\emph{limit} (i.e., the location immediately following its last element).
Let $v$ be the base and $\vl$ the limit of a multiprecision integer array.
-The array itself is notated as $v .. \vl$. The array's size in words may be
+The array itself is notated as~$v .. \vl$. The array's size in words may be
computed as $\vl - v$ in the normal C fashion. The integer represented by
the array, denoted $\mp(v .. \vl)$, is defined to be
\[
\mp(v .. \vl) =
\sum_{0 \le i < \vl - v}
- 2^{\code{MPW_BITS} \cdot i} v[i]
+ 2^{\code{MPW_BITS} \cdot i} v[i]
\]
If the array is empty (i.e., $v = \vl$) then the number is zero. If the
array is empty, or the final word is nonzero, then the representation is said
no difference to the final result anyway.
Whenever a result is too large to be represented in the memory allocated for
-it, high-order bits are discarded. Thus, a result written to an array of $k$
-words is reduced modulo $2^{\code{MPW_BITS} \cdot k}$.
+it, high-order bits are discarded. Thus, a result written to an array of
+$k$~words is reduced modulo $2^{\code{MPW_BITS} \cdot k}$.
\subsection{Low-level macros}
\fsec{Description}
-The \code{MPX_SHRINK} macro reduces the limit $\vl$ of a multiprecision
-integer array so that either $v = \vl$ or $\vl[-1] \ne 0$. The $\vl$
-argument must be an lvalue, since the macro writes the result back when it
+The \code{MPX_SHRINK} macro reduces the limit~$\vl$ of a multiprecision
+integer array so that either $v = \vl$ or~$\vl[-1] \ne 0$. The argument~$\vl$ must be an lvalue, since the macro writes the result back when it
finishes.
\subsubsection{The \code{MPX_BITS} macro}
\fsec{Description}
Determines the smallest number of bits which could represent the number
-$\mp(v .. \vl)$, and writes the answer to $b$, which must therefore be an
+$\mp(v .. \vl)$, and writes the answer to~$b$, which must therefore be an
lvalue. The result is zero if the number is zero; otherwise $b$ is the
largest integer such that
\[ \mp(v .. \vl) \ge 2^{(b - 1) \bmod \code{MPW_BITS}}.\]
\begin{listinglist}
|#include <catacomb/mpx.h>| \\
|MPX_OCTETS(size_t |$o$|,|
- |const mpw *|$v$|, const mpw *|$\vl$|);|
+ |const mpw *|$v$|, const mpw *|$\vl$|);|
\end{listinglist}
\fsec{Description}
Determines the smallest number of octets which could represent the number
-$\mp(v .. \vl)$, and writes the answer to $o$, which must therefore be an
+$\mp(v .. \vl)$, and writes the answer to~$o$, which must therefore be an
lvalue. This is useful for determining appropriate buffer sizes for the
results of \code{mpx_storel} and \code{mpx_storeb}.
-The result $o$ can be calculated from the number of bits $b$ reported by
+The result $o$ can be calculated from the number of bits~$b$ reported by
\code{MPX_BITS} as $o = \lceil b / 8 \rceil$; the algorithm used by
\code{MPX_OCTETS} is more efficient than this, however.
\begin{listinglist}
|#include <catacomb/mpx.h>| \\
|MPX_COPY(mpw *|$\dv$|, mpw *|$\dvl$|,|
- |const mpw *|$\av$|, const mpw *|$\avl$|);|
+ |const mpw *|$\av$|, const mpw *|$\avl$|);|
\end{listinglist}
\fsec{Description}
\begin{listinglist}
|#include <catacomb/mpx.h>| \\
|void mpx_storel(const mpw *|$v$|, const mpw *|$\vl$|,|
- |void *|$p$|, size_t |$\sz$|);|
+ |void *|$p$|, size_t |$\sz$|);|
\end{listinglist}
\fsec{Description}
-Stores the number held in the array $v .. \vl$ to the array of $\sz$ octets
-starting at address $p$ in little-endian byte order (i.e., least significant
+Stores the number held in the array $v .. \vl$ to the array of $\sz$~octets
+starting at address~$p$ in little-endian byte order (i.e., least significant
byte first).
\subsubsection{The \code{mpx_loadl} function}
\begin{listinglist}
|#include <catacomb/mpx.h>| \\
|void mpx_loadl(mpw *|$v$|, mpw *|$\vl$|,|
- |const void *|$p$|, size_t |$\sz$|);|
+ |const void *|$p$|, size_t |$\sz$|);|
\end{listinglist}
\fsec{Description}
-Loads into the array $v .. \vl$ the number represented in the array of $\sz$
-octets starting at address $p$ in little-endian byte order (i.e., least
+Loads into the array $v .. \vl$ the number represented in the array of
+$\sz$~octets starting at address~$p$ in little-endian byte order (i.e., least
significant byte first).
\subsubsection{The \code{mpx_storeb} function}
\begin{listinglist}
|#include <catacomb/mpx.h>| \\
|void mpx_storeb(const mpw *|$v$|, const mpw *|$\vl$|,|
- |void *|$p$|, size_t |$\sz$|);|
+ |void *|$p$|, size_t |$\sz$|);|
\end{listinglist}
\fsec{Description}
-Stores the number held in the array $v .. \vl$ to the array of $\sz$ octets
-starting at address $p$ in big-endian byte order (i.e., least significant
+Stores the number held in the array $v .. \vl$ to the array of $\sz$~octets
+starting at address~$p$ in big-endian byte order (i.e., least significant
byte last).
\subsubsection{The \code{mpx_loadb} function}
\begin{listinglist}
|#include <catacomb/mpx.h>| \\
|void mpx_loadb(mpw *|$v$|, mpw *|$\vl$|,|
- |const void *|$p$|, size_t |$\sz$|);|
+ |const void *|$p$|, size_t |$\sz$|);|
\end{listinglist}
\fsec{Description}
-Loads into the array $v .. \vl$ the number represented in the array of $\sz$
-octets starting at address $p$ in big-endian byte order (i.e., least
+Loads into the array $v .. \vl$ the number represented in the array of
+$\sz$~octets starting at address $p$ in big-endian byte order (i.e., least
significant byte last).
\begin{tabbing}
|#include <catacomb/mpx.h>| \\
|void mpx_lsl(|\=|mpw *|$\dv$|, mpw *|$\dvl$|,| \\
- \>|const mpw *|$\av$|, const mpw *|$\avl$|, size_t |$n$|);|
+ \>|const mpw *|$\av$|, const mpw *|$\avl$|, size_t |$n$|);|
\end{tabbing}
\end{listinglist}
\fsec{Description}
-Stores in $\dv .. \dvl$ the result of shifting $\mp(\av .. \avl)$ left by $n$
-bits (i.e., multiplying it by $2^n$).
+Stores in $\dv .. \dvl$ the result of shifting $\mp(\av .. \avl)$ left by
+$n$~bits (i.e., multiplying it by~$2^n$).
\subsubsection{The \code{mpx_lsr} function}
\label{fn:mpx-lsr}
\begin{tabbing}
|#include <catacomb/mpx.h>| \\
|void mpx_lsr(|\=|mpw *|$\dv$|, mpw *|$\dvl$|,| \\
- \>|const mpw *|$\av$|, const mpw *|$\avl$|, size_t |$n$|);|
+ \>|const mpw *|$\av$|, const mpw *|$\avl$|, size_t |$n$|);|
\end{tabbing}
\end{listinglist}
\fsec{Description}
Stores in $\dv .. \dvl$ the result of shifting $\mp(\av .. \avl)$ right by
-$n$ bits (i.e., dividing it by $2^n$, rounding towards zero).
+$n$~bits (i.e., dividing it by~$2^n$, rounding towards zero).
-\subsection{Low level arithmetic}
+\subsection{Low-level arithmetic}
The remaining functions perform standard arithmetic operations on large
integers. The form for the arguments is fairly well-standardized:
\begin{listinglist}
|#include <catacomb/mpx.h>| \\
|void mpx_2c(mpw *|$\dv$|, mpw *|$\dvl$|,|
- |const mpw *|$v$|, const mpw *|$\vl$|);|
+ |const mpw *|$v$|, const mpw *|$\vl$|);|
\end{listinglist}
\fsec{Description}
\begin{tabbing}
|#include <catacomb/mpx.h>| \\
|int mpx_ucmp(|\=|const mpw *|$\av$|, const mpw *|$\avl$|,| \\
- \>|const mpw *|$\bv$|, const mpw *|$\bvl$|);| \\
+ \>|const mpw *|$\bv$|, const mpw *|$\bvl$|);| \\
|int MPX_UCMP(|\=|const mpw *|$\av$|, const mpw *|$\avl$|, |\synt{rel-op}|,|
- \\ \>|const mpw *|$\bv$|, const mpw *|$\bvl$|);|
+ \\ \>|const mpw *|$\bv$|, const mpw *|$\bvl$|);|
\end{tabbing}
\end{listinglist}
\fsec{Description}
The function \code{mpx_ucmp} performs an unsigned comparison of two unsigned
-multiprecision integers $a$ and $b$, passed in the arrays $\av .. \avl$ and
+multiprecision integers $a$ and~$b$, passed in the arrays $\av .. \avl$ and
$\bv .. \bvl$ respectively.
The macro \code{MPX_UCMP} provides a slightly more readable interface for
The function \code{mpx_ucmp} returns a value less then, equal to, or
greater than zero depending on whether $a$ is less than, equal to or greater
-than $b$.
+than~$b$.
The macro \code{MPX_UCMP} returns a nonzero result if $a
\mathrel{\synt{rel-op}} b$ is true, and zero if false.
\begin{tabbing}
|#include <catacomb/mpx.h>| \\
|void mpx_uadd(|\=|mpw *|$\dv$|, mpw *|$\dvl$|,|
- |const mpw *|$\av$|, const mpw *|$\avl$|,| \\
- \>|const mpw *|$\bv$|, const mpw *|$\bvl$|);|
+ |const mpw *|$\av$|, const mpw *|$\avl$|,| \\
+ \>|const mpw *|$\bv$|, const mpw *|$\bvl$|);|
\end{tabbing}
\end{listinglist}
\fsec{Description}
-The function \code{mpx_uaddn} adds a small integer $n$ (expressed as a single
+The function \code{mpx_uaddn} adds a small integer~$n$ (expressed as a single
\code{mpw}) to the multiprecision integer held in $\dv .. \dvl$.
The macro \code{MPX_UADDN} performs exactly the same operation, but uses
\begin{tabbing}
|#include <catacomb/mpx.h>| \\
|void mpx_usub(|\=|mpw *|$\dv$|, mpw *|$\dvl$|,|
- |const mpw *|$\av$|, const mpw *|$\avl$|,| \\
- \>|const mpw *|$\bv$|, const mpw *|$\bvl$|);|
+ |const mpw *|$\av$|, const mpw *|$\avl$|,| \\
+ \>|const mpw *|$\bv$|, const mpw *|$\bvl$|);|
\end{tabbing}
\end{listinglist}
Subtracts one multiprecision integer from another. The difference of the two
arguments $\mp(\av .. \avl) - \mp(\bv .. \bvl)$ is stored in $\dv .. \dvl$.
The destination array may be equal to either or both source
-arrays.\footnote{%
+arrays.\footnote{%
Subtracting a number from itself is a particularly poor way of clearing an
integer to zero. A call to \code{MPX_ZERO} (page~\pageref{fn:MPX-ZERO}) is
much more efficient.} %
\fsec{Description}
-The function \code{mpx_usubn} subtracts a small integer $n$ (expressed as a
+The function \code{mpx_usubn} subtracts a small integer~$n$ (expressed as a
single \code{mpw}) from the multiprecision integer held in $\dv .. \dvl$.
The macro \code{MPX_USUBN} performs exactly the same operation, but uses
\begin{tabbing}
|#include <catacomb/mpx.h>| \\
|void mpx_umul(|\=|mpw *|$\dv$|, mpw *|$\dvl$|,|
- |const mpw *|$\av$|, const mpw *|$\avl$|,| \\
- \>|const mpw *|$\bv$|, const mpw *|$\bvl$|);|
+ |const mpw *|$\av$|, const mpw *|$\avl$|,| \\
+ \>|const mpw *|$\bv$|, const mpw *|$\bvl$|);|
\end{tabbing}
\end{listinglist}
\begin{tabbing}
|#include <catacomb/mpx.h>| \\
|void mpx_umuln(|\=|mpw *|$\dv$|, mpw *|$\dvl$|,| \\
- \> |const mpw *|$\av$|, const mpw *|$\avl$|, mpw |$n$|);| \\
+ \> |const mpw *|$\av$|, const mpw *|$\avl$|, mpw |$n$|);| \\
|void MPX_UMULN(|\=|mpw *|$\dv$|, mpw *|$\dvl$|,| \\
- \> |const mpw *|$\av$|, const mpw *|$\avl$|, mpw |$n$|);|
+ \> |const mpw *|$\av$|, const mpw *|$\avl$|, mpw |$n$|);|
\end{tabbing}
\end{listinglist}
\fsec{Description}
The function \code{mpx_umuln} multiplies the multiprecision integer passed in
-$\av .. \avl$ by a small integer $n$ (expressed as a single \code{mpw}),
+$\av .. \avl$ by a small integer~$n$ (expressed as a single \code{mpw}),
writing the product $n \cdot \mp(\av .. \avl)$ to the destination array $\dv
.. \dvl$. The destination array may be equal to the source array $\av
.. \avl$.
\begin{tabbing}
|#include <catacomb/mpx.h>| \\*
|void mpx_umlan(|\=|mpw *|$\dv$|, mpw *|$\dvl$|,| \\*
- \> |const mpw *|$\av$|, const mpw *|$\avl$|, mpw |$n$|);| \\
+ \> |const mpw *|$\av$|, const mpw *|$\avl$|, mpw |$n$|);| \\
|void MPX_UMLAN(|\=|mpw *|$\dv$|, mpw *|$\dvl$|,| \\
- \> |const mpw *|$\av$|, const mpw *|$\avl$|, mpw |$n$|);|
+ \> |const mpw *|$\av$|, const mpw *|$\avl$|, mpw |$n$|);|
\end{tabbing}
\end{listinglist}
\fsec{Description}
The function \code{mpx_umlan} multiplies the multiprecision integer passed in
-$\av .. \avl$ by a small integer $n$ (expressed as a single \code{mpw}), and
+$\av .. \avl$ by a small integer~$n$ (expressed as a single \code{mpw}), and
adds it to the value already stored in the destination array $\dv .. \dvl$.
The destination array may be equal to the source array $\av .. \avl$,
although this isn't very useful.
\begin{listinglist}
|#include <catacomb/mpx.h>| \\
|void mpx_usqr(mpw *|$\dv$|, mpw *|$\dvl$|,|
- |const mpw *|$\av$|, const mpw *|$\avl$|);|
+ |const mpw *|$\av$|, const mpw *|$\avl$|);|
\end{listinglist}
\fsec{Description}
\begin{tabbing}
|#include <catacomb/mpx.h>| \\
|void mpx_udiv(|\=|mpw *|$\qv$|, mpw *|$\qvl$|, mpw *|$\rv$|, mpw *|$\rvl$|,|
-\\ \>|const mpw *|$\dv$|, const mpw *|$\dvl$|,|
- |mpw *|$\mathit{sv}$|, mpw *|$\mathit{svl}$|);|
+\\ \>|const mpw *|$\dv$|, const mpw *|$\dvl$|,|
+ |mpw *|$\mathit{sv}$|, mpw *|$\mathit{svl}$|);|
\end{tabbing}
\end{listinglist}
which is a useful property when performing modular reductions.
\shortverb\|
-%%% Local Variables:
+%%% Local Variables:
%%% mode: latex
%%% TeX-master: "catacomb"
-%%% End:
+%%% End:
projects / u / mdw / catacomb / blobdiff