commit 781e9d05388539d989e3578ebc7f8a7cd038aeb0
Author: Mattias Andrée <maandree_AT_kth.se>
AuthorDate: Tue Nov 29 23:55:29 2016 +0100
Commit: Mattias Andrée <maandree_AT_kth.se>
CommitDate: Tue Nov 29 23:55:29 2016 +0100
Fix errors in the manual (most of them found by Ivan Zuboff)
Signedoffby: Mattias Andrée <maandree_AT_kth.se>
diff git a/doc/arithmetic.tex b/doc/arithmetic.tex
index 2e15a75..2c5a9d3 100644
 a/doc/arithmetic.tex
+++ b/doc/arithmetic.tex
_AT_@ 69,7 +69,7 @@ instruction specifically for performing
addition with ripplecarry over multiple words,
adds twos numbers plus the carry from the
last addition. libzahl uses assembly to
implement this efficiently. If however, an
+implement this efficiently. If, however, an
assembly implementation is not available for
the on which machine it is running, libzahl
implements ripplecarry less efficiently
_AT_@ 80,8 +80,8 @@ the compiler is known to support this
extension, it is implemented using inefficient
pure C code. This last resort manually
predicts whether an addition will overflow;
this could be made more efficent, but never
using the highest bit, in each character,
+this could be made more efficient, by never
+using the highest bit in each character,
except to detect overflow. This optimisation
is however not implemented because it is
not deemed important enough and would
_AT_@ 100,9 +100,9 @@ inplace operation:
\noindent
Use this whenever possible, it will improve
your performance, as it will involve less
CPU instructions for each characteraddition
+CPU instructions for each character addition
and it may be possible to eliminate some
characteradditions.
+character additions.
\newpage
_AT_@ 138,7 +138,7 @@ These function \emph{do not} allow {\tt NULL}
for the output parameters: {\tt quotient} and
{\tt remainder}. The quotient and remainder are
calculated simultaneously and indivisibly, hence
{\tt zdivmod} is provided to calculated both, if
+{\tt zdivmod} is provided to calculated both; if
you are only interested in the quotient or only
interested in the remainder, use {\tt zdiv} or
{\tt zmod}, respectively.
_AT_@ 146,14 +146,14 @@ interested in the remainder, use {\tt zdiv} or
These functions calculate a truncated quotient.
That is, the result is rounded towards zero. This
means for example that if the quotient is in
$(1,~1)$, {\tt quotient} gets 0. That that, this
+$(1,~1)$, {\tt quotient} gets 0. That is, this % TODO try to clarify
would not be the case for one of the sides of zero.
For example, if the quotient would have been
floored, negative quotients would have been rounded
away from zero. libzahl only provides truncated
division,
+division.
The remain is defined such that $n = qd + r$ after
+The remainder is defined such that $n = qd + r$ after
calling {\tt zdivmod(q, r, n, d)}. There is no
difference in the remainer between {\tt zdivmod}
and {\tt zmod}. The sign of {\tt d} has no affect
_AT_@ 188,7 +188,7 @@ lend you a hand.
% Floored division
\begin{alltt}
 void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
+ void \textcolor{c}{/* \textrm{All arguments must be unique.} */}
divmod_floor(z_t q, z_t r, z_t n, z_t d)
\{
zdivmod(q, r, n, d);
_AT_@ 199,7 +199,7 @@ lend you a hand.
% Ceiled division
\begin{alltt}
 void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
+ void \textcolor{c}{/* \textrm{All arguments must be unique.} */}
divmod_ceiling(z_t q, z_t r, z_t n, z_t d)
\{
zdivmod(q, r, n, d);
_AT_@ 214,7 +214,7 @@ lend you a hand.
% commercial rounding
\begin{alltt}
/* \textrm{This is how we normally round numbers.} */
 void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
+ void \textcolor{c}{/* \textrm{All arguments must be unique.} */}
divmod_half_from_zero(z_t q, z_t r, z_t n, z_t d)
\{
zdivmod(q, r, n, d);
_AT_@ 237,7 +237,7 @@ not award you a faceslap. % Had positive punishment
% This rounding method is also called:
% round half away from infinity
\begin{alltt}
 void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
+ void \textcolor{c}{/* \textrm{All arguments must be unique.} */}
divmod_half_to_zero(z_t q, z_t r, z_t n, z_t d)
\{
zdivmod(q, r, n, d);
_AT_@ 254,7 +254,7 @@ not award you a faceslap. % Had positive punishment
% This rounding method is also called:
% round half towards positive infinity
\begin{alltt}
 void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
+ void \textcolor{c}{/* \textrm{All arguments must be unique.} */}
divmod_half_up(z_t q, z_t r, z_t n, z_t d)
\{
int cmp;
_AT_@ 272,7 +272,7 @@ not award you a faceslap. % Had positive punishment
% This rounding method is also called:
% round half towards negative infinity
\begin{alltt}
 void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
+ void \textcolor{c}{/* \textrm{All arguments must be unique.} */}
divmod_half_down(z_t q, z_t r, z_t n, z_t d)
\{
int cmp;
_AT_@ 297,7 +297,7 @@ not award you a faceslap. % Had positive punishment
% bankers' rounding
% It is the default rounding method used in IEEE 754.
\begin{alltt}
 void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
+ void \textcolor{c}{/* \textrm{All arguments must be unique.} */}
divmod_half_to_even(z_t q, z_t r, z_t n, z_t d)
\{
int cmp;
_AT_@ 316,7 +316,7 @@ not award you a faceslap. % Had positive punishment
% Division with round half to odd
\newpage
\begin{alltt}
 void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
+ void \textcolor{c}{/* \textrm{All arguments must be unique.} */}
divmod_half_to_odd(z_t q, z_t r, z_t n, z_t d)
\{
int cmp;
_AT_@ 342,7 +342,7 @@ not award you a faceslap. % Had positive punishment
Currently, libzahl uses an almost trivial division
algorithm. It operates on positive numbers. It begins
by leftshifting the divisor as must as possible with
+by leftshifting the divisor as much as possible with
letting it exceed the dividend. Then, it subtracts
the shifted divisor from the dividend and add 1,
leftshifted as much as the divisor, to the quotient.
_AT_@ 350,7 +350,7 @@ The quotient begins at 0. It then rightshifts
the shifted divisor as little as possible until
it no longer exceeds the diminished dividend and
marks the shift in the quotient. This process is
repeated on till the unshifted divisor is greater
+repeated until the unshifted divisor is greater
than the diminished dividend. The final diminished
dividend is the remainder.
_AT_@ 376,7 +376,7 @@ exponentiation are
\noindent
They are identical, except {\tt zpowu} expects
and intrinsic type as the exponent. Both functions
+an intrinsic type as the exponent. Both functions
calculate
\vspace{1em}
_AT_@ 410,7 +410,7 @@ exponentiation by squaring. {\tt zmodpow} and
{\tt zmodpowu} are optimised, they modulate
results for multiplication and squaring at
every multiplication and squaring, rather than
modulating every at the end. Exponentiation
+modulating the result at the end. Exponentiation
by modulation is a very simple algorithm which
can be expressed as a simple formula
diff git a/doc/bitoperations.tex b/doc/bitoperations.tex
index 1a1494a..d7998f8 100644
 a/doc/bitoperations.tex
+++ b/doc/bitoperations.tex
_AT_@ 160,7 +160,7 @@ calculate division by a power of two and
modulus a power of two efficiently using
bitshift and bittruncation operations. libzahl
also has a bitsplit operation that can be used
to efficently calculate both division and
+to efficiently calculate both division and
modulus a power of two efficiently in the same
operation, or equivalently, storing low bits
in one integer and high bits in another integer.
diff git a/doc/getstarted.tex b/doc/getstarted.tex
index 0b297ed..282634d 100644
 a/doc/getstarted.tex
+++ b/doc/getstarted.tex
_AT_@ 58,7 +58,7 @@ are done using it, for example before the program exits.
\}}
\end{alltt}
{\tt zunsetup} all memory that has been reclaimed to
+{\tt zunsetup} frees all memory that has been reclaimed to
the memory pool, and all memory allocated by {\tt zsetup}.
Note that this does not free integers that are still
in use. It is possible to simply call {\tt zunsetup}
diff git a/doc/libzahl.tex b/doc/libzahl.tex
index c0e3f43..a5609d6 100644
 a/doc/libzahl.tex
+++ b/doc/libzahl.tex
_AT_@ 78,7 +78,7 @@ copyright notice and this permission notice appear in all copies.}
% It should look just like a sentience except it may not end with a
% period unless that is part of an ellipsis or an abbreviation.
% I would also like to use straight apostrophes, like in French, (and
% reserve the curved ones for quotes,) but that is just too painful in
+% reserve the curved ones for quotes), but that is just too painful in
% LaTeX, so I will only be do so for French words. Most style guides
% for English will be followed. They will only be broken if they are
% stupid or inferior. For example, I will never write ‘CPU's’ for
diff git a/doc/libzahlsdesign.tex b/doc/libzahlsdesign.tex
index dcc2cb1..b3eb701 100644
 a/doc/libzahlsdesign.tex
+++ b/doc/libzahlsdesign.tex
_AT_@ 155,7 +155,7 @@ allows you do so if you so choose.
The {\tt .sign} member, is either $1$, 0, or 1,
when the integer is negative, zero, or positive,
respectively. Whenever, {\tt .sign} is 0, the value
+respectively. Whenever {\tt .sign} is 0, the value
of {\tt .used} and {\tt .chars} are undefined.
{\tt .used} holds to the number of elements used in
_AT_@ 192,7 +192,7 @@ they are not considered input integers. The order
of the input parameters are that of the order you
would write them using mathematical notation, this
also holds true if you include the output parameter
(as long as there is exactly one output,) for example
+(as long as there is exactly one output), for example
\vspace{1em}
$a \gets b^c \mod d$
_AT_@ 256,7 +256,7 @@ This assumption is not made for noncommutative
functions.
When writting your own functions, be aware,
inputparameters are generally not declared {\tt const}
+input parameters are generally not declared {\tt const}
in libzahl. Currently, some functions actually make
modifications (that do not affect the value) to
inputparameters.
+input parameters.
diff git a/doc/miscellaneous.tex b/doc/miscellaneous.tex
index 312d01c..8750595 100644
 a/doc/miscellaneous.tex
+++ b/doc/miscellaneous.tex
_AT_@ 65,7 +65,7 @@ a proper UCS minus sign is not supported.
Using what we have learned so far, and {\tt zstr}
which we will learn about in \secref{sec:String output},
we can construct a simple program that calculates the
sum of a set of number.
+sum of a set of numbers.
\begin{alltt}
\textcolor{c}{#include <stdio.h>
_AT_@ 153,10 +153,10 @@ there are cases where it is needed. In some case
\noindent
however its implementation is optimised to be
around three times as fast. It just swaps the members
of the parameters, and thereby the values, There
+of the parameters, and thereby the values. There
is no rewriting of {\tt .chars} involved; thus
it runs in constant time. It also does not
require that any argument has be initialised.
+require that any argument has been initialised.
After the call, {\tt a} will be initialised
if and only if {\tt b} was initialised, and
vice versa.
_AT_@ 301,11 +301,11 @@ The return for {\tt zcmpmag} value is defined
\vspace{1em}
\noindent
It is discouraged, stylistically, to compare
against, $1$ and $+1$, rather, you should
always compare against $0$. Think of it as
returning $a  b$, or $\lvert a \rvert  \lvert b \rvert$
in the case of {\tt zcmpmag}.
+It is discouraged, stylistically, to compare against
+$1$ and $+1$, rather, you should always compare
+against $0$. Think of it as returning $a  b$, or
+$\lvert a \rvert  \lvert b \rvert$ in the case of
+{\tt zcmpmag}.
\newpage
_AT_@ 320,7 +320,7 @@ run the same version of libzahl, and run on compatible
microarchitectures, that is, the processors must have
endianness, and the intrinsic integer types in C must
have the same widths on all processors. When this is not
the case, string conversion (see \secref{sec:Assignment}
+the case, string conversion can be used (see \secref{sec:Assignment}
and \secref{sec:String output}), but when it is the case
{\tt zsave} and {\tt zload} can be used. {\tt zsave} and
{\tt zload} are declared as
_AT_@ 331,11 +331,11 @@ and \secref{sec:String output}), but when it is the case
\end{alltt}
\noindent
{\tt zsave} stores a version and microarchitecturedepend
+{\tt zsave} stores a version and microarchitecturedependent
binary representation of {\tt a} in {\tt buf}, and returns
the number of bytes written to {\tt buf}. If {\tt buf} is
{\tt NULL}, the numbers that will be written is returned.
{\tt zload} unmarshals an integers from {\tt buf}, created
with {\tt zsave}, into {\tt a}, and returns the number of
read bytes. {\tt zload} and will return the value returned
by {\tt zsave}.
+{\tt NULL}, the numbers bytes that would have be written is
+returned. {\tt zload} unmarshals an integers from {\tt buf},
+created with {\tt zsave}, into {\tt a}, and returns the number
+of read bytes. {\tt zload} returns the value returned by
+{\tt zsave}.
diff git a/doc/notimplemented.tex b/doc/notimplemented.tex
index 9b3c6cb..59b3efb 100644
 a/doc/notimplemented.tex
+++ b/doc/notimplemented.tex
_AT_@ 84,9 +84,12 @@ more about this, I refer you to Wikipeida.
\( \displaystyle{
\mbox{lcm}(a, b) = \frac{\lvert a \cdot b \rvert}{\mbox{gcd}(a, b)}
}\)
+\vspace{1em}
Be aware, {\tt zgcd} can return zero.

+$\mbox{lcm}(a, b)$ is undefined when $a$ or
+$b$ is zero, because division by zero is
+undefined. Note however that $\mbox{gcd}(a, b)$
+is only zero when both $a$ and $b$ is zero.
\newpage
\section{Modular multiplicative inverse}
_AT_@ 309,7 +312,7 @@ TODO % Square: Cipolla's algorithm, Pocklington's algorithm, Tonelli–Shanks al
}\)
\vspace{1em}
This can be implemented much more efficently
+This can be implemented much more efficiently
than using the naïve method, and is a very
important function for many combinatorial
applications, therefore it may be implemented
diff git a/doc/whatislibzahl.tex b/doc/whatislibzahl.tex
index e09d0bd..b0e80f5 100644
 a/doc/whatislibzahl.tex
+++ b/doc/whatislibzahl.tex
_AT_@ 57,8 +57,8 @@ it can still be improved. Furthermore, GNU MP cannot be
used for robust applications.
\item
LibTomMath is very slow, infact performance is not its
priority, rather its simplicit is the priority. Despite
+LibTomMath is very slow, in fact performance is not its
+priority, rather its simplicity is the priority. Despite
this, it is not really that simple.
\item
_AT__AT_ 73,8 +73,8 @@ philosophy.\footnote{\href{
http://suckless.org/philosophy}
{
http://suckless.org/philosophy}} libzahl is simple,
very fast, simple to use, and can be used in robust
applications. Currently however, it does not support
multithreading, but it has better support multiprocessing
and distributed computing than its competitor.
+multithreading, but it has better support for multiprocessing
+and distributed computing than its competitors.
Lesser ``competitors'' (less known) to libzahl include
Hebimath and bsdnt.
_AT_@ 142,10 +142,10 @@ caught using {\tt setjmp}. This ensure that it can be
used in robust applications, catching errors does not
become a mess, and it minimises the overhead of
catching errors. Errors are only checked when they can
occur, not also after each functionreturn.
+occur, not also after each function return.
Additionally, libzahl tries to keep the functions'
names simple and natural rather than techniqual or
+names simple and natural rather than technical or
mathematical. The names resemble those of the standard
integer operators. For example, the leftshift, rightshift
and truncation bitoperations in libzahl are called
_AT_@ 214,6 +214,19 @@ strictly necessary for it to be an CPUintrinsic,
but that would be favourable for performance.)
\end{itemize}
+Because of the prevalence of theses properties
+in contemporary machines, and the utilisation of
+these properties in software, especially software
+for POSIX and popular platforms with similar
+properties, any new generalpurpose machine most
+have these properties lest, it but useless with
+today's software. Therefore, libzahl can make
+the assumption that the machine has these
+properties. If the machine does not have these
+properties, the compiler must compensate for
+these machines deficiencies, making it generally
+slower.
+
These limitations may be removed later. And there
is some code that does not make these assumptions
but acknowledge that it may be a case. On the other
Received on Tue Nov 29 2016  23:55:44 CET