source: project/wiki/eggref/4/mathh @ 34505

Last change on this file since 34505 was 34505, checked in by kon, 3 months ago

rel 3.2.1

File size: 12.2 KB
Line 
1[[tags: egg]]
2
3== mathh
4
5[[toc:]]
6
7
8== Documentation
9
10Provides access to ISO C math functions in <math.h> that are not defined by
11the Chicken core. Please refer to your documentation for <math.h> for a
12description of the various calls.
13
14
15=== Math Functions
16
17{{O}}, {{P2}} are {{integer}}.
18
19{{N}}, {{N1}}, {{N2}}, {{M}} are {{real}}.
20
21==== Usage
22
23<enscript language=scheme>
24(use "mathh")
25</enscript>
26
27==== bessel-j0
28==== bessel-j1
29==== bessel-jn
30==== bessel-jn
31==== bessel-y0
32==== bessel-y1
33==== bessel-yn
34
35<procedure>(bessel-j0 N) => real</procedure>
36<procedure>(bessel-j1 N) => real</procedure>
37<procedure>(bessel-jn O N) => real</procedure>
38<procedure>(bessel-y0 N) => real</procedure>
39<procedure>(bessel-y1 N) => real</procedure>
40<procedure>(bessel-yn O N) => real</procedure>
41
42==== cosh
43==== sinh
44==== tanh
45==== acosh
46==== asinh
47==== atanh
48
49<procedure>(cosh N) => real</procedure>
50<procedure>(sinh N) => real</procedure>
51<procedure>(tanh N) => real</procedure>
52<procedure>(acosh N) => real</procedure>
53<procedure>(asinh N) => real</procedure>
54<procedure>(atanh N) => real</procedure>
55
56==== hypot
57
58<procedure>(hypot N1 N2) => real</procedure>
59
60==== gamma
61==== lgamma
62
63<procedure>(gamma N) => real</procedure>
64<procedure>(lgamma N) => real</procedure>
65
66==== erf
67==== erfc
68
69<procedure>(erf N) => real</procedure>
70<procedure>(erfc N) => real</procedure>
71
72==== log10
73==== log2
74==== log1p
75
76<procedure>(log10 N) => real</procedure>
77<procedure>(log2 N) => real</procedure>
78<procedure>(log1p N) => real</procedure>
79
80==== make-log/base
81
82<procedure>(make-log/base N) => (provedure (real) real)</procedure>
83
84Returns a procedure of one argument, the logarithm function for the base {{N}}.
85
86==== ldexp
87==== scalbn
88
89<procedure>(ldexp N P2) => real</procedure>
90<procedure>(scalbn N P2) => real</procedure>
91
92==== cbrt
93
94<procedure>(cbrt N) => real</procedure>
95
96==== nextafter
97
98<procedure>(nextafter N M) => real</procedure>
99
100Returns the next {{N}} in the direction of {{M}}.
101
102==== fpmod
103
104<procedure>(fpmod N M) => real</procedure>
105
106Returns the modulus of {{N}} for {{M}}.
107
108==== modf
109
110<procedure>(modf N) => (values real integer)</procedure>
111
112Returns two values, the integral and fractional components of {{N}}.
113
114==== frexp
115
116<procedure>(frexp N) => (values real real)</procedure>
117
118Returns two values, the fraction and the exponent components of {{N}}.
119
120==== signbit
121
122<procedure>(signbit N) => boolean</procedure>
123
124Returns {{#t}} when negative, {{#f}} otherwise.
125
126==== copysign
127
128<procedure>(copysign N M) => real</procedure>
129
130Returns {{N}} with same sign as {{M}}.
131
132==== fpclassify
133
134<procedure>(fpclassify N) => symbol</procedure>
135
136Returns a symbol denoting the floating-point kind of {{N}}.
137
138; infinite :
139; nan :
140; normal :
141; subnormal :
142; zero :
143; unclassified :
144
145==== fpclass
146
147<procedure>(fpclass N) => symbol</procedure>
148
149Returns a symbol denoting the floating-point kind of {{N}}.
150
151; positive-infinite :
152; negative-infinite :
153; quiet-nan :
154; signaling-nan :
155; positive-normal :
156; negative-normal :
157; positive-subnormal :
158; negative-subnormal :
159; positive-zero :
160; negative-zero :
161; unclassified :
162
163
164=== Flonum Utilities
165
166==== Usage
167
168<enscript language=scheme>
169(require-extension fp-utils)
170</enscript>
171
172{{N N1 ... X1 ... Y1 ...}} below are {{flonum}}.
173
174{{P}} is the precision in decimal digits, an {{integer}}.
175
176==== fprandom
177
178<procedure>(fprandom [N]) => flonum</procedure>
179
180{{N}} {{fixnum}} limit.
181
182==== fpzero?
183
184<procedure>(fpzero? N) => boolean</procedure>
185
186==== fppositive?
187
188<procedure>(fppositive? N) => boolean</procedure>
189
190==== fpcardinal?
191
192<procedure>(fpcardinal? N) => boolean</procedure>
193
194==== fpnegative?
195
196<procedure>(fpnegative? N) => boolean</procedure>
197
198==== fpeven?
199
200<procedure>(fpeven? N) => boolean</procedure>
201
202==== fpodd?
203
204<procedure>(fpodd? N) => boolean</procedure>
205
206==== fpclosed-right?
207==== fpclosedr?
208
209<procedure>(fpclosed-right? L N H) => boolean</procedure>
210<procedure>(fpclosedr? L N H) => boolean</procedure>
211
212Returns {{N}} in {{(L .. H]}}.
213
214{{N}}, {{L}} & {{H}} are {{flonum}} low & high limits.
215
216==== fpclosed?
217
218Returns {{N}} in {{[L .. H]}}.
219
220<procedure>(fpclosed? L N H) => boolean</procedure>
221
222{{N}}, {{L}} & {{H}} are {{flonum}} low & high limits.
223
224==== fpclosed-left?
225==== fpclosedl?
226
227Returns {{N}} in {{[L .. H)}}.
228
229<procedure>(fpclosed-left? L N H) => boolean</procedure>
230<procedure>(fpclosedl? L N H) => boolean</procedure>
231
232{{N}}, {{L}} & {{H}} are {{flonum}} low & high limits.
233
234==== fpadd1
235
236<procedure>(fpadd1 N) => flonum</procedure>
237
238==== fpsub1
239
240<procedure>(fpsub1 N) => flonum</procedure>
241
242==== fpmodulo
243
244<procedure>(fpmodulo N1 N2) => flonum</procedure>
245
246==== fpquotient
247
248<procedure>(fpquotient N1 N2) => flonum</procedure>
249
250==== fpremainder
251
252<procedure>(fpremainder N1 N2) => flonum</procedure>
253
254==== fpfraction
255
256<procedure>(fpfraction N) => flonum</procedure>
257
258==== fptruncate/precision
259
260<procedure>(fptruncate/precision N [P 4]) => flonum</procedure>
261
262==== fpround/precision
263
264<procedure>(fpround/precision N [P 4]) => flonum</procedure>
265
266==== fpceiling/precision
267
268<procedure>(fpceiling/precision N [P 4]) => flonum</procedure>
269
270==== fpfloor/precision
271
272<procedure>(fpfloor/precision N [P 4]) => flonum</procedure>
273
274==== fp~=
275
276<procedure>(fp~= N1 N2 [EPS flonum-epsilon]) => flonum</procedure>
277
278Compare floating-point values {{N1}} and {{N2}} within some {{flonum}} epsilon
279{{EPS}}.
280
281==== fp~<=
282
283<procedure>(fp~<= N) => boolean</procedure>
284
285==== fp~>=
286
287<procedure>(fp~>= N) => boolean</procedure>
288
289==== fpsqr
290
291<procedure>(fpsqr N) => flonum</procedure>
292
293==== fpcub
294
295<procedure>(fpcub N) => flonum</procedure>
296
297==== fpdegree->radian
298
299<procedure>(fpdegree->radian N) => flonum</procedure>
300
301==== fpradian->degree
302
303<procedure>(fpradian->degree N) => flonum</procedure>
304
305==== fpdistance
306
307<procedure>(fpdistance X1 Y1 X2 Y2) => flonum</procedure>
308
309Pythagorean distance between the points {{X1 Y1}} and {{X2 Y2}}.
310
311==== fpdistance*
312
313<procedure>(fpdistance* X1 Y1 X2 Y2) => flonum</procedure>
314
315Pythagorean distance, inaccurate but useful for relative comparisons.
316
317==== fpmax-and-min
318
319<procedure>(fpmax-and-min N ...) => (values flonum flonum)</procedure>
320
321Returns the maximum & minimum values for the {{flonum}}s {{N ...}}.
322
323==== fpprecision-factor
324
325<procedure>(fpprecision-factor P [BASE 10.0]) => flonum</procedure>
326
327Returns factor for {{P}} decimal digits precision.
328
329
330=== Fixnum Utilities
331
332==== Usage
333
334<enscript language=scheme>
335(require-extension fx-utils)
336</enscript>
337
338{{N N1 ... X1 ... Y1 ...}} below are {{fixnum}}.
339
340==== fxrandom
341
342<procedure>(fxrandom [N]) => fixnum</procedure>
343
344{{N}} {{fixnum}} limit.
345
346==== fxzero?
347
348<procedure>(fxzero? N) => boolean</procedure>
349
350==== fxpositive?
351
352<procedure>(fxpositive? N) => boolean</procedure>
353
354==== fxcardinal?
355
356<procedure>(fxcardinal? N) => boolean</procedure>
357
358==== fxnegative?
359
360<procedure>(fxnegative? N) => boolean</procedure>
361
362==== fxclosed-right?
363==== fxclosedr?
364
365<procedure>(fxclosed-right? L N H) => boolean</procedure>
366<procedure>(fxclosedr? L N H) => boolean</procedure>
367
368Returns {{N}} in {{(L .. H]}}.
369
370{{N}}, {{L}} & {{H}} are {{fixnum}} low & high limits.
371
372==== fxclosed?
373
374Returns {{N}} in {{[L .. H]}}.
375
376<procedure>(fxclosed? L N H) => boolean</procedure>
377
378{{N}}, {{L}} & {{H}} are {{fixnum}} low & high limits.
379
380==== fxclosed-left?
381==== fxclosedl?
382
383Returns {{N}} in {{[L .. H)}}.
384
385<procedure>(fxclosed-left? L N H) => boolean</procedure>
386<procedure>(fxclosedl? L N H) => boolean</procedure>
387
388{{N}}, {{L}} & {{H}} are {{fixnum}} low & high limits.
389
390==== fxadd1
391
392<procedure>(fxadd1 N) => fixnum</procedure>
393
394==== fxsub1
395
396<procedure>(fxsub1 N) => fixnum</procedure>
397
398==== fxabs
399
400<procedure>(fxabs N) => fixnum</procedure>
401
402==== fxsqr
403
404<procedure>(fxsqr N) => fixnum</procedure>
405
406==== fxcub
407
408<procedure>(fxcub N) => fixnum</procedure>
409
410==== fxpow2log2
411
412<procedure>(fxpow2log2 N) => fixnum</procedure>
413
414Returns {{fixnum}} {{2^N}}.
415
416==== fxdistance
417
418<procedure>(fxdistance X1 Y1 X2 Y2) => fixnum</procedure>
419
420Pythagorean distance between the points {{X1 Y1}} and {{X2 Y2}}.
421
422==== fxdistance*
423
424<procedure>(fxdistance* X1 Y1 X2 Y2) => fixnum</procedure>
425
426Pythagorean distance, inaccurate but useful for relative comparisons.
427
428==== fxmax-and-min
429
430<procedure>(fxmax-and-min N ...) => (values fixnum fixnum)</procedure>
431
432Returns the maximum & minimum values for the {{fixnum}}s {{N ...}}.
433
434
435=== Math Constants (Module)
436
437==== Usage
438
439<enscript language=scheme>
440(require-extension mathh-consts)
441</enscript>
442
443==== Constants
444
445These are all {{flonum}}.
446
447; e : e
448; 1/e : 1/e
449; e^2 : e^2
450; e^pi/4 : e^(pi/4)
451; log2e : log2(e)
452; log10e : log10(e)
453; ln2 : log(2)
454; ln3 : ln(3)
455; lnpi : ln(pi)
456; ln10 : log(10)
457; 1/ln2 : 1/ln(2)
458; 1/ln10 : 1/ln(10)
459; pi : pi
460; pi/2 : pi/2
461; pi/4 : pi/4
462; 1/pi : 1/pi
463; 2/pi : 2/pi
464; 2/sqrtpi : 2/sqrt(pi)
465; sqrtpi : sqrt(pi)
466; pi^2 : pi^2
467; degree : pi/180
468; sqrt2 : sqrt(2)
469; 1/sqrt2 : 1/sqrt(2)
470; sqrt3 : sqrt(3)
471; sqrt5 : sqrt(5)
472; sqrt10 : sqrt(10)
473; cubert2 : cubert(2)
474; cubert3 : cubert(3)
475; 4thrt2 : fourthrt(2)
476; gamma1/2 : gamma(1/2)
477; gamma1/3 : gamma(1/3)
478; gamma2/3 : gamma(2/3)
479; phi : phi
480; lnphi : ln(phi)
481; 1/lnphi : 1/ln(phi)
482; euler : euler
483; e^euler : e^euler
484; sin1 : sin(1)
485; cos1 : cos(1)
486; zeta3 : theta(3)
487
488
489=== Math Constants (Include)
490
491Common constants, using 'define-constant'. As such they must be textually
492included.
493
494==== Usage
495
496<enscript language=scheme>
497(include "mathh-constants")
498</enscript>
499
500==== Constants
501
502; E : e
503; 1/E : 1/e
504; E^2 : e^2
505; E^PI/4 : e^(pi/4)
506; LOG2E : log2(e)
507; LOG10E : log10(e)
508; LN2 : log(2)
509; LN3 : ln(3)
510; LNPI : ln(pi)
511; LN10 : log(10)
512; 1/LN2 : 1/ln(2)
513; 1/LN10 : 1/ln(10)
514; PI : pi
515; PI/2 : pi/2
516; PI/4 : pi/4
517; 1/PI : 1/pi
518; 2/PI : 2/pi
519; 2/SQRTPI : 2/sqrt(pi)
520; SQRTPI : sqrt(pi)
521; PI^2 : pi^2
522; DEGREE : pi/180
523; SQRT2 : sqrt(2)
524; 1/SQRT2 : 1/sqrt(2)
525; SQRT3 : sqrt(3)
526; SQRT5 : sqrt(5)
527; SQRT10 : sqrt(10)
528; CUBERT2 : cubert(2)
529; CUBERT3 : cubert(3)
530; 4THRT2 : fourthrt(2)
531; GAMMA1/2 : gamma(1/2)
532; GAMMA1/3 : gamma(1/3)
533; GAMMA2/3 : gamma(2/3)
534; PHI : phi
535; LNPHI : ln(phi)
536; 1/LNPHI : 1/ln(phi)
537; EULER : euler
538; E^EULER : e^euler
539; SIN1 : sin(1)
540; COS1 : cos(1)
541; ZETA3 : theta(3)
542
543
544== Notes
545
546* The C library call {{gamma}} is deprecated in favor of {{tgamma}} but not
547available yet on some platforms, so we use {{gamma}} where necessary.
548
549* Some library calls that are not supplied by the platform have rough
550implementations supplied. See {{Bugs and Limitations}}.
551
552* The general naming convention is to use the C library call name as the Scheme
553name. But there are exceptions:
554
555; fmod : fpmod - ''fp-utils'' {{fpmodulo}} - should be in Chicken library?
556; j0 : bessel-j0 (Prefixed to distinguish the names from common variables)
557; j1 : bessel-j1
558; jn : bessel-jn
559; y0 : bessel-y0
560; y1 : bessel-y1
561; yn : bessel-yn
562
563== Bugs and Limitations
564
565* CHICKEN_INCLUDE_PATH must at least state the value of the
566{{(repository-path)}} to include ''mathh-constants.scm''. Suggest using the
567module ''mathh-consts''.
568
569* The types {{integer}} & {{real}} refer to the Chicken "core" concept of a
570number. Support for the full numeric tower is '''not''' provided.
571
572*  Windows does not provide library calls {{lgamma}}, {{gamma}}, {{acosh}},
573{{asinh}}, {{atanh}}, {{log2}}, {{log1p}}, {{erf}}, {{erfc}}, {{scalbn}},
574{{cbrt}} & {{signbit}}.
575
576Usable {{log2}}, {{log1p}}, {{erf}}, {{erfc}}, {{scalbn}} & {{signbit}} are
577supplied.
578
579* FreeBSD does not provide the library call {{log2}}. A usable {{log2}} is
580supplied.
581
582* The {{fpclass}} {{quiet-nan}} is only distinguished on Windows.
583
584* ''fx-utils.scm'' & ''fp-utils.scm'' belong in own eggs.
585
586* The compiler option '-inline-global' causes problems; so no -O3+.
587
588
589== Author
590
591[[/users/kon-lovett|Kon Lovett]]
592[[/users/john cowan|John Cowan]]
593
594
595== Version history
596
597; 3.2.1 ; Add types. Fix {{signbit}} & {{fpclass}}.
598; 3.2.0 ; Fix {{fpodd?}}. Add ''fx-utils.scm''. Extend ''fp-utils.scm''.
599; 3.1.0 ; Added module for ''mathh-constants.scm''.
600; 3.0.0 ; Moved copy of ''mathh-constants.scm'' to {{(chicken-home)}}. Ticket #1327
601; 2.2.6 ; better argvector chicken test
602; 2.2.5 ; argvector chicken support
603; 2.2.4 ;
604; 2.2.3 ; Fix for ticket #630
605; 2.2.2 ; ''mathh-constants.scm'' copied to Chicken Repository. Produces shared+static object files.
606; 2.2.1 : Better ''no-install'' support.
607; 2.2.0 : Added {{acosh}}, {{asinh}}, {{atanh}}, {{erf}} & {{erfc}}. Includes <sunmath.h> on Sun platform for {{log2}}.
608; 2.1.0 : Added {{signbit}}, {{copysign}}, {{nextafter}} & {{cbrt}}.
609; 2.0.0 : Chicken 4 release. {{fpclass}} and {{fpclassify}} are now part of the '''mathh''' extension.
610
611
612== License
613
614This code is in the public domain.
Note: See TracBrowser for help on using the repository browser.