libzahl

big integer library
git clone git://git.suckless.org/libzahl
Log | Files | Refs | README | LICENSE

commit 5990e4e42754a84edfaed2a31ee5cea3c4c9d9b1
parent a541877c84e798e5a46c76f4cf4c362cfdcebae2
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:
doc/arithmetic.tex | 36+++++++++++++++++++++++++++++++++++-
doc/libzahl.tex | 26+++++++++++++++++++++++++-
doc/what-is-libzahl.tex | 13+++++++------
3 files changed, 67 insertions(+), 8 deletions(-)

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 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 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