refsheet.tex - libzahl - big integer library
(HTM) git clone git://git.suckless.org/libzahl
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
refsheet.tex (7771B)
---
1 \documentclass[10pt]{article}
2 \usepackage[margin=1in]{geometry}
3 \usepackage{amsmath, amssymb, mathtools}
4 \usepackage{microtype}
5 \DeclarePairedDelimiter\ab{\lvert}{\rvert}
6
7 \newcommand{\size}{{\tt size\_t}}
8 \newcommand{\ullong}{{\tt unsigned long long int}}
9
10 \newcommand{\entry}[3]{ #2 & {\tt #1} & #3 \\ }
11 \newcommand{\cont}[1]{ & & #1 \\ }
12
13 \begin{document}
14
15
16
17 {\Huge libzahl}
18 \vspace{1ex}
19
20 Unless specified otherwise, returns are {\tt void} and all parameters are of type {\tt z\_t}.
21 \vspace{1.5em}
22
23
24
25 \hspace{-2ex}
26 \begin{tabular}{lll}
27
28
29
30 \textbf{Initialisation} \\
31 \entry{zsetup(env)} {Initialise libzahl} {must be called before any other function is}
32 \cont {used, {\tt env} is a {\tt jmp\_buf} all functions will}
33 \cont {{\tt longjmp} to --- with value 1 --- on error}
34 \entry{zunsetup()} {Deinitialise libzahl} {will free any pooled memory}
35 \entry{zinit(a)} {Initialise $a$} {call once before use in any other function}
36 \entry{zfree(a)} {Deinitialise $a$} {must not be used again before reinitialisation}
37 \\
38
39 \textbf{Error handling} \\
40 \entry{zerror(a)} {Get error code} {returns {\tt enum zerror}, and stores}
41 \cont {description in {\tt const char **a}}
42 \entry{zperror(a)} {Print error description} {behaves like {\tt perror(a)}, {\tt a} is a,}
43 \cont {possibly {\tt NULL} or $\varepsilon$, {\tt const char *}}
44 %\\
45
46 \textbf{Arithmetic} \\
47 \entry{zadd(a, b, c)} {$a \gets b + c$} {}
48 \entry{zsub(a, b, c)} {$a \gets b - c$} {}
49 \entry{zmul(a, b, c)} {$a \gets b \cdot c$} {}
50 \entry{zmodmul(a, b, c, d)} {$a \gets b \cdot c \mod d$} {$0 \le a~\mbox{sgn}~bc < \ab{d}$}
51 \entry{zdiv(a, b, c)} {$a \gets b / c$} {rounded towards zero}
52 \entry{zdivmod(a, b, c, d)} {$a \gets c / d$} {rounded towards zero}
53 \entry{zdivmod(a, b, c, d)} {$b \gets c \mod d$} {$0 \le b~\mbox{sgn}~c < \ab{d}$}
54 \entry{zmod(a, b, c)} {$a \gets b \mod c$} {$0 \le a~\mbox{sgn}~b < \ab{c}$}
55 %\entry{zdiv\_exact(a, b, c)} {$a \gets b / c$} {assumes $c \vert d$}
56 \entry{zsqr(a, b)} {$a \gets b^2$} {}
57 \entry{zmodsqr(a, b, c)} {$a \gets b^2 \mod c$} {$0 \le a < \ab{c}$}
58 \entry{zsqr(a, b)} {$a \gets b^2$} {}
59 \entry{zpow(a, b, c)} {$a \gets b^c$} {}
60 \entry{zpowu(a, b, c)} {$a \gets b^c$} {{\tt c} is an \ullong{}}
61 \entry{zmodpow(a, b, c, d)} {$a \gets b^c \mod d$} {$0 \le a~\mbox{sgn}~b^c < \ab{d}$}
62 \entry{zmodpowu(a, b, c, d)} {$a \gets b^c \mod d$} {ditto, {\tt c} is an \ullong{}}
63 \entry{zabs(a, b)} {$a \gets \ab{b}$} {}
64 \entry{zneg(a, b)} {$a \gets -b$} {}
65 \\
66
67 \textbf{Assignment} \\
68 \entry{zset(a, b)} {$a \gets b$} {}
69 \entry{zseti(a, b)} {$a \gets b$} {{\tt b} is an {\tt int64\_t}}
70 \entry{zsetu(a, b)} {$a \gets b$} {{\tt b} is a {\tt uint64\_t}}
71 \entry{zsets(a, b)} {$a \gets b$} {{\tt b} is a decimal {\tt const char *}}
72 %\entry{zsets\_radix(a, b, c)} {$a \gets b$} {{\tt b} is a radix $c$ {\tt const char *},}
73 %\cont {{\tt c} is an \ullong{}}
74 \entry{zswap(a, b)} {$a \leftrightarrow b$} {}
75 \\
76
77 \textbf{Comparison} \\
78 \entry{zcmp(a, b)} {Compare $a$ and $b$} {returns {\tt int} $\mbox{sgn}(a - b)$}
79 \entry{zcmpi(a, b)} {Compare $a$ and $b$} {ditto, {\tt b} is an {\tt int64\_t}}
80 \entry{zcmpu(a, b)} {Compare $a$ and $b$} {ditto, {\tt b} is a {\tt uint64\_t}}
81 \entry{zcmpmag(a, b)} {Compare $\ab{a}$ and $\ab{b}$} {returns {\tt int} $\mbox{sgn}(\ab{a} - \ab{b})$}
82 \\
83
84
85
86 \end{tabular}
87 \newpage
88 \hspace{-2ex}
89 \begin{tabular}{lll}
90
91
92
93 \textbf{Bit operation} \\
94 \entry{zand(a, b, c)} {$a \gets b \wedge c$} {bitwise}
95 \entry{zor(a, b, c)} {$a \gets b \vee c$} {bitwise}
96 \entry{zxor(a, b, c)} {$a \gets b \oplus c$} {bitwise}
97 \entry{znot(a, b, c)} {$a \gets \lnot b$} {bitwise, cut at highest set bit}
98 \entry{zlsh(a, b, c)} {$a \gets b \cdot 2^c$} {{\tt c} is a \size{}}
99 \entry{zrsh(a, b, c)} {$a \gets b / 2^c$} {ditto, rounded towards zero}
100 \entry{ztrunc(a, b, c)} {$a \gets b \mod 2^c$} {ditto, $a$ shares signum with $b$}
101 \entry{zbits(a)} {Get number of used bits} {returns \size{}, 1 if $a = 0$}
102 \entry{zlsb(a)} {Get index of lowest set bit} {returns \size{}, {\tt SIZE\_MAX} if $a = 0$}
103 \entry{zbtest(a, b)} {Is bit $b$ in $a$ set?} {{\tt b} is a \size{}, returns {\tt int}}
104 \entry{zbset(a, b, c, 1)} {$a \gets b$, set bit $c$} {{\tt c} is a \size{}}
105 \entry{zbset(a, b, c, 0)} {$a \gets b$, clear bit $c$} {ditto}
106 \entry{zbset(a, b, c, -1)} {$a \gets b$, flip bit $c$} {ditto}
107 \entry{zsplit(a, b, c, d)} {$a \gets c / 2^d$} {{\tt d} is a \size{}, rounded towards zero}
108 \entry{zsplit(a, b, c, d)} {$b \gets c \mod 2^d$} {ditto, $b$ shares signum with $c$}
109 \\
110
111 \textbf{Conversion to string} \\
112 \entry{zstr(a, b, c)} {Convert $a$ to decimal} {returns the resulting {\tt const char *}}
113 \cont {--- {\tt b} unless {\tt b} is
114 {\tt NULL}, --- $c$ must be}
115 \cont {either 0 or at least the length of the}
116 \cont {resulting string but at most the}
117 \cont {allocation size of {\tt b} minus 1}
118 %\entry{zstr\_radix(a, b, c, d)} {Convert $a$ to radix $d$} {ditto, {\tt d} is an \ullong{}}
119 \entry{zstr\_length(a, b)} {Get string length of $a$} {returns \size{} length of $a$ in radix $b$}
120 \\
121
122 \textbf{Marshallisation} \\
123 \entry{zsave(a, b)} {Marshal $a$ into $b$} {returns \size{} number of saved bytes,}
124 \cont {{\tt b} is a {\tt void *}}
125 \entry{zsave(a, NULL)} {Get marshal-size of $a$} {returns \size{}}
126 \entry{zload(a, b)} {Unmarshal $a$ from $b$} {returns \size{} number of read bytes,}
127 \cont {{\tt b} is a {\tt const void *}}
128 %\\
129
130 \textbf{Number theory} \\
131 \entry{zsignum(a, b)} {$a \gets \mbox{sgn}~b$} {}
132 \entry{zeven(a)} {Is $a$ even?} {returns {\tt int} 1 (true) or 0 (false)}
133 \entry{zeven\_nonzero(a)} {Is $a$ even?} {ditto, assumes $a \neq 0$}
134 \entry{zodd(a)} {Is $a$ odd?} {returns {\tt int} 1 (true) or 0 (false)}
135 \entry{zodd\_nonzero(a)} {Is $a$ odd?} {ditto, assumes $a \neq 0$}
136 \entry{zzero(a)} {Is $a$ zero?} {returns {\tt int} 1 (true) or 0 (false)}
137 \entry{zgcd(a, b, c)} {$a \gets \gcd(c, b)$} {$a < 0$ if $b < 0 \wedge c < 0$}
138 \entry{zptest(a, b, c)} {Is $b$ a prime?} {$c$ runs of Miller--Rabin, returns}
139 \cont {{\tt enum zprimality} {\tt NONPRIME} (0)}
140 \cont {(and stores the witness in {\tt a} unless}
141 \cont {{\tt a} is {\tt NULL}), {\tt PROBABLY\_PRIME} (1), or}
142 \cont {{\tt PRIME} (2)}
143 %\\
144
145 \textbf{Randomness} \\
146 \entry{zrand(a, b, UNIFORM, d)} {$a \xleftarrow{\$} \textbf{Z}_d$}
147 {{\tt b} is a {\tt enum zranddev}, e.g.}
148 \cont {{\tt DEFAULT\_RANDOM}, {\tt FASTEST\_RANDOM}}
149 \\
150
151
152
153 \end{tabular}
154 \end{document}