Commit | Line | Data |
---|---|---|
82d8c5f9 C |
1 | ." $Header: ch3.n 1.3 83/06/21 13:00:48 sklower Exp $ |
2 | .Lc Arithmetic\ Functions 3 | |
3 | .pp | |
4 | This chapter describes | |
5 | .Fr "'s" | |
6 | functions for doing arithmetic. | |
7 | Often the same function is known by many names, such as | |
8 | .i add | |
9 | which is also | |
10 | .i plus , | |
11 | .i sum , | |
12 | and \(pl. | |
13 | This is due to our desire to be compatible with other Lisps. | |
14 | The | |
15 | .Fr | |
16 | user is advised to avoid using functions with names | |
17 | such as \(pl and \(** unless | |
18 | their arguments are fixnums. | |
19 | The Lisp compiler takes advantage of the fact that their | |
20 | arguments are fixnums. | |
21 | .pp | |
22 | An attempt to divide or to generate a floating | |
23 | point result outside of the range of | |
24 | floating point numbers | |
25 | will cause a floating exception signal | |
26 | from the UNIX operating system. | |
27 | The user can catch and process this interrupt if desired (see the | |
28 | description of the | |
29 | .i signal | |
30 | function). | |
31 | .sh 2 simple\ arithmetic\ functions \n(ch 1 | |
32 | .Lf add "['n_arg1 ...]" | |
33 | .Lx plus "['n_arg1 ...]" | |
34 | .Lx sum "['n_arg1 ...]" | |
35 | .Lx \(pl "['x_arg1 ...]" | |
36 | .Re | |
37 | the sum of the arguments. If no arguments are given, 0 is returned. | |
38 | .No | |
39 | if the size of the partial sum exceeds the limit of a fixnum, the | |
40 | partial sum will be converted to a bignum. | |
41 | If any of the arguments are flonums, the partial sum will be | |
42 | converted to a flonum when that argument is processed and the | |
43 | result will thus be a flonum. | |
44 | Currently, if in the process of doing the | |
45 | addition a bignum must be converted into | |
46 | a flonum an error message will result. | |
47 | .Lf add1 'n_arg | |
48 | .Lx 1+ 'x_arg | |
49 | .Re | |
50 | its argument plus 1. | |
51 | .Lf diff "['n_arg1 ... ]" | |
52 | .Lx difference "['n_arg1 ... ]" | |
53 | .Lx \(mi "['x_arg1 ... ]" | |
54 | .Re | |
55 | the result of subtracting from n_arg1 all subsequent arguments. | |
56 | If no arguments are given, 0 is returned. | |
57 | .No | |
58 | See the description of add for details on data type conversions and | |
59 | restrictions. | |
60 | .Lf sub1 "'n_arg" | |
61 | .Lx 1\(mi "'x_arg" | |
62 | .Re | |
63 | its argument minus 1. | |
64 | .Lf minus "'n_arg" | |
65 | .Re | |
66 | zero minus n_arg. | |
67 | .Lf product "['n_arg1 ... ]" | |
68 | .Lx times "['n_arg1 ... ]" | |
69 | .Lx \(** "['x_arg1 ... ]" | |
70 | .Re | |
71 | the product of all of its arguments. | |
72 | It returns 1 if there are no arguments. | |
73 | .No | |
74 | See the description of the function \fIadd\fP for details and restrictions to the | |
75 | automatic data type coercion. | |
76 | .Lf quotient "['n_arg1 ...]" | |
77 | .Lx / "['x_arg1 ...]" | |
78 | .Re | |
79 | the result of dividing the first argument by succeeding ones. | |
80 | .No | |
81 | If there are no arguments, 1 is returned. | |
82 | See the description of the function \fIadd\fP for details and restrictions | |
83 | of data type coercion. | |
84 | A divide by zero will cause a floating exception interrupt -- see | |
85 | the description of the | |
86 | .i signal | |
87 | function. | |
88 | .Lf *quo "'i_x 'i_y" | |
89 | .Re | |
90 | the integer part of i_x / i_y. | |
91 | .Lf Divide "'i_dividend 'i_divisor" | |
92 | .Re | |
93 | a list whose car is the quotient and whose cadr is the remainder of the | |
94 | division of i_dividend by i_divisor. | |
95 | .No | |
96 | this is restricted to integer division. | |
97 | .Lf Emuldiv "'x_fact1 'x_fact2 'x_addn 'x_divisor" | |
98 | .Re | |
99 | a list of the quotient and remainder of this operation: | |
100 | ((x_fact1\ *\ x_fact2)\ +\ (sign\ extended)\ x_addn)\ /\ x_divisor. | |
101 | .No | |
102 | this is useful for creating a bignum arithmetic package in Lisp. | |
103 | .sh 2 predicates | |
104 | .Lf numberp "'g_arg" | |
105 | .Lf numbp "'g_arg" | |
106 | .Re | |
107 | t iff g_arg is a number (fixnum, flonum or bignum). | |
108 | .Lf fixp "'g_arg" | |
109 | .Re | |
110 | t iff g_arg is a fixnum or bignum. | |
111 | .Lf floatp "'g_arg" | |
112 | .Re | |
113 | t iff g_arg is a flonum. | |
114 | .Lf evenp "'x_arg" | |
115 | .Re | |
116 | t iff x_arg is even. | |
117 | .Lf oddp "'x_arg" | |
118 | .Re | |
119 | t iff x_arg is odd. | |
120 | .Lf zerop "'g_arg" | |
121 | .Re | |
122 | t iff g_arg is a number equal to 0. | |
123 | .Lf onep "'g_arg" | |
124 | .Re | |
125 | t iff g_arg is a number equal to 1. | |
126 | .Lf plusp "'n_arg" | |
127 | .Re | |
128 | t iff n_arg is greater than zero. | |
129 | .Lf minusp "'g_arg" | |
130 | .Re | |
131 | t iff g_arg is a negative number. | |
132 | .Lf greaterp "['n_arg1 ...]" | |
133 | .Lx > "'fx_arg1 'fx_arg2" | |
134 | .Lx >& "'x_arg1 'x_arg2" | |
135 | .Re | |
136 | t iff the arguments are in a strictly decreasing order. | |
137 | .No | |
138 | In functions | |
139 | .i greaterp | |
140 | and | |
141 | .i > | |
142 | the function | |
143 | .i difference | |
144 | is used to compare adjacent values. | |
145 | If any of the arguments are non-numbers, the error message will come | |
146 | from the | |
147 | .i difference | |
148 | function. | |
149 | The arguments to | |
150 | .i > | |
151 | must be fixnums or both flonums. | |
152 | The arguments to | |
153 | .i >& | |
154 | must both be fixnums. | |
155 | .Lf lessp "['n_arg1 ...]" | |
156 | .Lx < "'fx_arg1 'fx_arg2" | |
157 | .Lx <& "'x_arg1 'x_arg2" | |
158 | .Re | |
159 | t iff the arguments are in a strictly increasing order. | |
160 | .No | |
161 | In functions | |
162 | .i lessp | |
163 | and | |
164 | .i < | |
165 | the function \fIdifference\fP is used to compare adjacent values. | |
166 | If any of the arguments are non numbers, the error message will come | |
167 | from the \fIdifference\fP function. | |
168 | The arguments to | |
169 | .i < | |
170 | may be either fixnums or flonums but must be the same type. | |
171 | The arguments to | |
172 | .i <& | |
173 | must be fixnums. | |
174 | .Lf \(eq "'fx_arg1 'fx_arg2" | |
175 | .Lf \(eq& "'x_arg1 'x_arg2" | |
176 | .Re | |
177 | t iff the arguments have the same value. | |
178 | The arguments to \(eq must be the either both fixnums or both flonums. | |
179 | The arguments to \(eq& must be fixnums. | |
180 | .sh 2 trignometric\ functions | |
181 | .Lf cos "'fx_angle" | |
182 | .Re | |
183 | the (flonum) cosine of fx_angle (which is assumed to be in radians). | |
184 | .Lf sin "'fx_angle" | |
185 | .Re | |
186 | the sine of fx_angle (which is assumed to be in radians). | |
187 | .Lf acos "'fx_arg" | |
188 | .Re | |
189 | the (flonum) arc cosine of fx_arg in the range 0 to \(*p. | |
190 | .Lf asin "'fx_arg" | |
191 | .Re | |
192 | the (flonum) arc sine of fx_arg in the range \(mi\(*p/2 to \(*p/2. | |
193 | .Lf atan "'fx_arg1 'fx_arg2" | |
194 | .Re | |
195 | the (flonum) arc tangent of fx_arg1/fx_arg2 in the range -\(*p to \(*p. | |
196 | .sh 2 bignum\ functions | |
197 | .Lf haipart "bx_number x_bits" | |
198 | .Re | |
199 | a fixnum (or bignum) which contains | |
200 | the x_bits high bits of | |
201 | \fI(abs\ bx_number)\fP if x_bits is positive, otherwise | |
202 | it returns the \fI(abs\ x_bits)\fP low bits of \fI(abs\ bx_number)\fP. | |
203 | .Lf haulong "bx_number" | |
204 | .Re | |
205 | the number of significant bits in bx_number. | |
206 | .No | |
207 | the result is equal to the least integer greater to or equal to the | |
208 | base two logarithm of | |
209 | one plus the absolute value of bx_number. | |
210 | .Lf bignum-leftshift "bx_arg x_amount" | |
211 | .Re | |
212 | bx_arg shifted left by x_amount. If | |
213 | x_amount is negative, bx_arg will be shifted right by the magnitude of | |
214 | x_amount. | |
215 | .No | |
216 | If bx_arg is shifted right, it will be rounded to the nearest even number. | |
217 | .Lf sticky-bignum-leftshift "'bx_arg 'x_amount" | |
218 | .Re | |
219 | bx_arg shifted left by x_amount. If | |
220 | x_amount is negative, bx_arg will be shifted right by the magnitude of | |
221 | x_amount and rounded. | |
222 | .No | |
223 | sticky rounding is done this way: after shifting, | |
224 | the low order bit is changed to 1 | |
225 | if any 1's were shifted off to the right. | |
226 | .sh 2 bit\ manipulation | |
227 | .Lf boole "'x_key 'x_v1 'x_v2 ..." | |
228 | .Re | |
229 | the result of the bitwise boolean operation as described in the following | |
230 | table. | |
231 | .No | |
232 | If there are more than 3 arguments, then evaluation proceeds left to | |
233 | right with each partial result becoming the new value of x_v1. | |
234 | That is, | |
235 | .br | |
236 | \ \ \ \ \ \fI(boole\ 'key\ 'v1\ 'v2\ 'v3)\ \(==\ (boole\ 'key\ (boole\ 'key\ 'v1\ 'v2)\ 'v3)\fP. | |
237 | .br | |
238 | In the following table, \(** represents bitwise and, \(pl represents | |
239 | bitwise or, \o'\(ci\(pl' represents bitwise xor and \(no represents | |
240 | bitwise negation and is the highest precedence operator. | |
241 | .ps 8 | |
242 | .TS | |
243 | center box ; | |
244 | c s s s s s s s s | |
245 | c c c c c c c c c. | |
246 | (boole 'key 'x 'y) | |
247 | ||
248 | = | |
249 | key 0 1 2 3 4 5 6 7 | |
250 | result 0 x \(** y \(no x \(** y y x \(** \(no y x x \o'\(ci\(pl' y x \(pl y | |
251 | ||
252 | common | |
253 | names and bitclear xor or | |
254 | ||
255 | _ | |
256 | ||
257 | key 8 9 10 11 12 13 14 15 | |
258 | result \(no (x \(pl y) \(no(x \o'\(ci\(pl' y) \(no x \(no x \(pl y \(no y x \(pl \(no y \(no x \(pl \(no y -1 | |
259 | common | |
260 | names nor equiv implies nand | |
261 | .TE | |
262 | .ps 10 | |
263 | .pp | |
264 | .Lf lsh "'x_val 'x_amt" | |
265 | .Re | |
266 | x_val shifted left by x_amt if x_amt is positive. | |
267 | If x_amt is negative, then | |
268 | .i lsh | |
269 | returns x_val shifted right by the magnitude if x_amt. | |
270 | .No | |
271 | This always returns a fixnum even for those numbers whose magnitude is | |
272 | so large that they would normally be represented as a bignum, | |
273 | i.e. shifter bits are lost. | |
274 | For more general bit shifters, see | |
275 | .i bignum-leftshift | |
276 | and | |
277 | .i sticky-bignum-leftshift. | |
278 | .Lf rot "'x_val 'x_amt" | |
279 | .Re | |
280 | x_val rotated left by x_amt if x_amt is positive. | |
281 | If x_amt is negative, then x_val is rotated right by the magnitude of x_amt. | |
282 | .sh 2 other\ functions | |
283 | .Lf abs 'n_arg | |
284 | .Lx absval 'n_arg | |
285 | .Re | |
286 | the absolute value of n_arg. | |
287 | .Lf exp "'fx_arg" | |
288 | .Re | |
289 | .i e | |
290 | raised to the fx_arg power (flonum) . | |
291 | .Lf expt "'n_base 'n_power" | |
292 | .Re | |
293 | n_base raised to the n_power power. | |
294 | .No | |
295 | if either of the arguments are flonums, the calculation will be done using | |
296 | .i log | |
297 | and | |
298 | .i exp . | |
299 | .Lf fact "'x_arg" | |
300 | .Re | |
301 | x_arg factorial. (fixnum or bignum) | |
302 | .Lf fix "'n_arg" | |
303 | .Re | |
304 | a fixnum as close as we can get to n_arg. | |
305 | .No | |
306 | \fIfix\fP will round down. | |
307 | Currently, if n_arg is a flonum larger | |
308 | than the size of a fixnum, this will fail. | |
309 | .Lf float "'n_arg" | |
310 | .Re | |
311 | a flonum as close as we can get to n_arg. | |
312 | .No | |
313 | if n_arg is a bignum larger than the maximum size of a flonum, | |
314 | then a floating exception will occur. | |
315 | .Lf log "'fx_arg" | |
316 | .Re | |
317 | the natural logarithm of fx_arg. | |
318 | .Lf max "'n_arg1 ... " | |
319 | .Re | |
320 | the maximum value in the list of arguments. | |
321 | .Lf min "'n_arg1 ... " | |
322 | .Re | |
323 | the minimum value in the list of arguments. | |
324 | .Lf mod "'i_dividend 'i_divisor" | |
325 | .Lx remainder "'i_dividend 'i_divisor" | |
326 | .Re | |
327 | the remainder when i_dividend is divided by i_divisor. | |
328 | .No | |
329 | The sign of the result will have the same sign as i_dividend. | |
330 | .Lf *mod "'x_dividend 'x_divisor" | |
331 | .Re | |
332 | the balanced representation of x_dividend modulo x_divisor. | |
333 | .No | |
334 | the range of the balanced representation is abs(x_divisor)/2 to | |
335 | (abs(x_divisor)/2) \(mi x_divisor + 1. | |
336 | .Lf random "['x_limit]" | |
337 | .Re | |
338 | a fixnum between 0 and x_limit \(mi 1 if x_limit is given. | |
339 | If x_limit is not given, any fixnum, positive or negative, might be | |
340 | returned. | |
341 | .Lf sqrt "'fx_arg" | |
342 | .Re | |
343 | the square root of fx_arg. |