Some comments - libzahl - big integer library
(HTM) git clone git://git.suckless.org/libzahl
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
(DIR) commit 5990e4e42754a84edfaed2a31ee5cea3c4c9d9b1
(DIR) parent a541877c84e798e5a46c76f4cf4c362cfdcebae2
(HTM) Author: Mattias Andrée <maandree@kth.se>
Date: Thu, 2 Jun 2016 12:06:27 +0200
Some comments
Signed-off-by: Mattias Andrée <maandree@kth.se>
Diffstat:
M doc/arithmetic.tex | 36 ++++++++++++++++++++++++++++++-
M doc/libzahl.tex | 26 +++++++++++++++++++++++++-
M doc/what-is-libzahl.tex | 13 +++++++------
3 files changed, 67 insertions(+), 8 deletions(-)
---
(DIR) diff --git a/doc/arithmetic.tex b/doc/arithmetic.tex
@@ -186,6 +186,7 @@ lend you a hand.
\}
\end{alltt}
+% Floored division
\begin{alltt}
void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
divmod_floor(z_t q, z_t r, z_t n, z_t d)
@@ -196,9 +197,10 @@ lend you a hand.
\}
\end{alltt}
+% Ceiled division
\begin{alltt}
void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
- divmod_ceil(z_t q, z_t r, z_t n, z_t d)
+ divmod_ceiling(z_t q, z_t r, z_t n, z_t d)
\{
zdivmod(q, r, n, d);
if (!zzero(r) && isneg(n) == isneg(d))
@@ -206,6 +208,10 @@ lend you a hand.
\}
\end{alltt}
+% Division with round half aways from zero
+% This rounding method is also called:
+% round half toward infinity
+% commercial rounding
\begin{alltt}
/* \textrm{This is how we normally round numbers.} */
void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
@@ -227,6 +233,9 @@ not award you a face-slap. % Had positive punishment
% been legal or even mildly pedagogical. But I would
% not put it past Coca-Cola.
+% Division with round half toward zero
+% This rounding method is also called:
+% round half away from infinity
\begin{alltt}
void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
divmod_half_to_zero(z_t q, z_t r, z_t n, z_t d)
@@ -241,6 +250,9 @@ not award you a face-slap. % Had positive punishment
\}
\end{alltt}
+% Division with round half up
+% This rounding method is also called:
+% round half towards positive infinity
\begin{alltt}
void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
divmod_half_up(z_t q, z_t r, z_t n, z_t d)
@@ -256,6 +268,9 @@ not award you a face-slap. % Had positive punishment
\}
\end{alltt}
+% Division with round half down
+% This rounding method is also called:
+% round half towards negative infinity
\begin{alltt}
void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
divmod_half_down(z_t q, z_t r, z_t n, z_t d)
@@ -271,6 +286,16 @@ not award you a face-slap. % Had positive punishment
\}
\end{alltt}
+% Division with round half to even
+% This rounding method is also called:
+% unbiased rounding (really stupid name)
+% convergent rounding (also quite stupid name)
+% statistician's rounding
+% Dutch rounding
+% Gaussian rounding
+% odd–even rounding
+% bankers' rounding
+% It is the default rounding method used in IEEE 754.
\begin{alltt}
void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
divmod_half_to_even(z_t q, z_t r, z_t n, z_t d)
@@ -288,6 +313,7 @@ not award you a face-slap. % Had positive punishment
\}
\end{alltt}
+% Division with round half to odd
\newpage
\begin{alltt}
void \textcolor{c}{/* \textrm{All arguments most be unique.} */}
@@ -306,6 +332,14 @@ not award you a face-slap. % Had positive punishment
\}
\end{alltt}
+% Other standard methods include stochastic rounding
+% and round half alternatingly, and what is is
+% New Zealand called “Swedish rounding”, which is
+% no longer used in Sweden, and is just normal round
+% half aways from zero but with 0.5 rather than
+% 1 as the integral unit, and is just a special case
+% of a more general rounding method.
+
Currently, libzahl uses an almost trivial division
algorithm. It operates on positive numbers. It begins
by left-shifting the divisor as must as possible with
(DIR) diff --git a/doc/libzahl.tex b/doc/libzahl.tex
@@ -29,7 +29,9 @@
\geometry{margin=1in}
\usepackage{microtype}
\DisableLigatures{encoding = *, family = *} % NB! disables -- and ---
-\frenchspacing
+% I really dislike fi- and ff-ligatures, just like look so wrong.
+\frenchspacing % i.e. non-American spacing: i.e. no extra space after sentences,
+ % this also means that periods do not have to be context-marked.
\newcommand{\chapref}[1]{\hyperref[#1]{Chapter~\ref*{#1} [\nameref*{#1}], page \pageref*{#1}}}
\newcommand{\secref}[1]{\hyperref[#1]{Section~\ref*{#1} [\nameref*{#1}], page \pageref*{#1}}}
@@ -62,6 +64,28 @@ purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.}
\newpage
+
+% Conventionally, most words in a title in English should start with
+% uppercase. I believe that this is inconsistent stupidity, pardon my
+% Klatchian. There is not consensus of which words should not start
+% with lowercase or even if any shall start with lowercase. There is
+% also no consensus on how long the title should be before only the
+% first word should start with uppercase. It is only generally (but
+% not always) agreed that most words should start with uppercase and
+% when the title is too long only the first word start with uppercase.
+% I believe that is is better to stick with the Swedish convention:
+% 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
+% 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
+% plural of CPU — that's just stupid, — only for genitive, nor
+% will I write ‘CPUs’ for plural of CPU, because it is inferior to
+% ‘CPU:s’.
+
+
\shorttoc{Short contents}{0}
\setcounter{tocdepth}{2}
\dominitoc
(DIR) diff --git a/doc/what-is-libzahl.tex b/doc/what-is-libzahl.tex
@@ -15,8 +15,8 @@ what is its limitations.
\label{sec:The name and the what}
In mathematics, the set of all integers is represented
-by a bold uppercase `Z' ({\bf Z}), or sometimes
-double-stroked (blackboard bold) ($\mathbb{Z}$). This symbol
+by a bold uppercase `Z' ({\bf Z}), or sometimes % proper symbol
+double-stroked (blackboard bold) ($\mathbb{Z}$). This symbol % hand-written style, specially on whiteboards and blackboards
is derived from the german word for integers: `Zahlen'
[\textprimstress{}tsa\textlengthmark{}l\textschwa{}n],
whose singular is `Zahl' [tsa\textlengthmark{}l]. libzahl
@@ -100,8 +100,8 @@ followed by output parameters, and output parameters
followed by input parameters. The former variant is the
conventional for C functions. The latter is more in style
with primitive operations, pseudo-code, mathematics, and
-how it would look if the output was return. In libzahl,
-the latter convention is used. That is, we write
+how it would look if the output was return. In libzahl, the
+latter convention is used. That is, we write
\begin{alltt}
zadd(sum, augend, addend);
@@ -129,8 +129,9 @@ $augend + addend \rightarrow sum$.
\vspace{1em}
libzahl, GNU MP, and Hebimath use the output-first
-convention. LibTomMath and TomsFastMath use the
-input-first convention.
+convention.\footnote{GNU MP-style.} LibTomMath and
+TomsFastMath use the input-first convention.\footnote{BSD
+MP-style.}
Unlike other bignum libraries, errors in libzahl are
caught using {\tt setjmp}. This ensure that it can be