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

Last change on this file since 35314 was 35314, checked in by kon, 16 months ago

rel 3.4.2

File size: 13.0 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==== log-with-base
81
82<procedure>(log-with-base N) -> (procedure (real) real)</procedure>
83
84Returns a monadic function, the logarithm of 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
180Returns {{flonum}} in {{[0 -1)}}.
181
182; {{N}} : {{fixnum}} or {{flonum}} limit.
183
184==== fpzero?
185
186<procedure>(fpzero? N) -> boolean</procedure>
187
188==== fppositive?
189
190<procedure>(fppositive? N) -> boolean</procedure>
191
192Note that {{-0.0}} is '''not''' positive, due to {{(fl<? -0.0 0.0)}}.
193
194==== fpcardinal?
195
196<procedure>(fpcardinal? N) -> boolean</procedure>
197
198Note that {{-0.0}} is '''not''' cardinal, due to {{(fl<? -0.0 0.0)}}.
199
200==== fpnegative?
201
202<procedure>(fpnegative? N) -> boolean</procedure>
203
204Note that {{-0.0}} is '''not''' negative, due to {{(fl<? -0.0 0.0)}}.
205
206==== fpeven?
207
208<procedure>(fpeven? N) -> boolean</procedure>
209
210==== fpodd?
211
212<procedure>(fpodd? N) -> boolean</procedure>
213
214==== fpclosed-right?
215==== fpclosedr?
216
217<procedure>(fpclosed-right? L N H) -> boolean</procedure>
218<procedure>(fpclosedr? L N H) -> boolean</procedure>
219
220Returns {{N}} in {{(L .. H]}}.
221
222{{N}}, {{L}} & {{H}} are {{flonum}} low & high limits.
223
224==== fpclosed?
225
226Returns {{N}} in {{[L .. H]}}.
227
228<procedure>(fpclosed? L N H) -> boolean</procedure>
229
230{{N}}, {{L}} & {{H}} are {{flonum}} low & high limits.
231
232==== fpclosed-left?
233==== fpclosedl?
234
235Returns {{N}} in {{[L .. H)}}.
236
237<procedure>(fpclosed-left? L N H) -> boolean</procedure>
238<procedure>(fpclosedl? L N H) -> boolean</procedure>
239
240{{N}}, {{L}} & {{H}} are {{flonum}} low & high limits.
241
242==== fpadd1
243
244<procedure>(fpadd1 N) -> flonum</procedure>
245
246==== fpsub1
247
248<procedure>(fpsub1 N) -> flonum</procedure>
249
250==== fpmodulo
251
252<procedure>(fpmodulo N1 N2) -> flonum</procedure>
253
254==== fpquotient
255
256<procedure>(fpquotient N1 N2) -> flonum</procedure>
257
258==== fpremainder
259
260<procedure>(fpremainder N1 N2) -> flonum</procedure>
261
262==== fpfraction
263
264<procedure>(fpfraction N) -> flonum</procedure>
265
266==== fptruncate/precision
267
268<procedure>(fptruncate/precision N [P 4]) -> flonum</procedure>
269
270==== fpround/precision
271
272<procedure>(fpround/precision N [P 4]) -> flonum</procedure>
273
274==== fpceiling/precision
275
276<procedure>(fpceiling/precision N [P 4]) -> flonum</procedure>
277
278==== fpfloor/precision
279
280<procedure>(fpfloor/precision N [P 4]) -> flonum</procedure>
281
282==== fp~=
283
284<procedure>(fp~= N1 N2 [EPS flonum-epsilon]) -> flonum</procedure>
285
286Compare floating-point values {{N1}} and {{N2}} within some {{flonum}} epsilon
287{{EPS}}.
288
289==== fp~<=
290
291<procedure>(fp~<= N) -> boolean</procedure>
292
293==== fp~>=
294
295<procedure>(fp~>= N) -> boolean</procedure>
296
297==== fpsqr
298
299<procedure>(fpsqr N) -> flonum</procedure>
300
301==== fpcub
302
303<procedure>(fpcub N) -> flonum</procedure>
304
305==== fpdegree->radian
306
307<procedure>(fpdegree->radian N) -> flonum</procedure>
308
309==== fpradian->degree
310
311<procedure>(fpradian->degree N) -> flonum</procedure>
312
313==== fpdistance
314
315<procedure>(fpdistance X1 Y1 X2 Y2) -> flonum</procedure>
316
317Pythagorean distance between the points {{X1 Y1}} and {{X2 Y2}}.
318
319==== fpdistance*
320
321<procedure>(fpdistance* X1 Y1 X2 Y2) -> flonum</procedure>
322
323Pythagorean distance, inaccurate but useful for relative comparisons.
324
325==== fpmax-and-min
326
327<procedure>(fpmax-and-min N ...) -> (values flonum flonum)</procedure>
328
329Returns the maximum & minimum values for the {{flonum}}s {{N ...}}.
330
331==== fpprecision-factor
332
333<procedure>(fpprecision-factor P [BASE 10.0]) -> flonum</procedure>
334
335Returns factor for {{P}} decimal digits precision.
336
337
338=== Fixnum Utilities
339
340==== Usage
341
342<enscript language=scheme>
343(require-extension fx-utils)
344</enscript>
345
346{{N N1 ... X1 ... Y1 ...}} below are {{fixnum}}.
347
348==== fxrandom
349
350<procedure>(fxrandom [N]) -> fixnum</procedure>
351
352{{N}} {{fixnum}} limit.
353
354==== fxzero?
355
356<procedure>(fxzero? N) -> boolean</procedure>
357
358==== fxpositive?
359
360<procedure>(fxpositive? N) -> boolean</procedure>
361
362==== fxcardinal?
363
364<procedure>(fxcardinal? N) -> boolean</procedure>
365
366==== fxnegative?
367
368<procedure>(fxnegative? N) -> boolean</procedure>
369
370==== fxclosed-right?
371==== fxclosedr?
372
373<procedure>(fxclosed-right? L N H) -> boolean</procedure>
374<procedure>(fxclosedr? L N H) -> boolean</procedure>
375
376Returns {{N}} in {{(L .. H]}}.
377
378{{N}}, {{L}} & {{H}} are {{fixnum}} low & high limits.
379
380==== fxclosed?
381
382Returns {{N}} in {{[L .. H]}}.
383
384<procedure>(fxclosed? L N H) -> boolean</procedure>
385
386{{N}}, {{L}} & {{H}} are {{fixnum}} low & high limits.
387
388==== fxclosed-left?
389==== fxclosedl?
390
391Returns {{N}} in {{[L .. H)}}.
392
393<procedure>(fxclosed-left? L N H) -> boolean</procedure>
394<procedure>(fxclosedl? L N H) -> boolean</procedure>
395
396{{N}}, {{L}} & {{H}} are {{fixnum}} low & high limits.
397
398==== fxadd1
399
400<procedure>(fxadd1 N) -> fixnum</procedure>
401
402==== fxsub1
403
404<procedure>(fxsub1 N) -> fixnum</procedure>
405
406==== fxabs
407
408<procedure>(fxabs N) -> fixnum</procedure>
409
410==== fxsqr
411
412<procedure>(fxsqr N) -> fixnum</procedure>
413
414==== fxcub
415
416<procedure>(fxcub N) -> fixnum</procedure>
417
418==== fxlog2
419
420<procedure>(fxlog2 N) -> fixnum</procedure>
421
422Returns index of highest bit set, so {{N}} is treated as unsigned.
423
424==== fxpow2log2
425
426<procedure>(fxpow2log2 N) -> fixnum</procedure>
427
428Returns {{fixnum}} {{2^N}}.
429
430==== fxdistance
431
432<procedure>(fxdistance X1 Y1 X2 Y2) -> fixnum</procedure>
433
434Pythagorean distance between the points {{X1 Y1}} and {{X2 Y2}}.
435
436==== fxdistance*
437
438<procedure>(fxdistance* X1 Y1 X2 Y2) -> fixnum</procedure>
439
440Pythagorean distance, inaccurate but useful for relative comparisons.
441
442==== fxmax-and-min
443
444<procedure>(fxmax-and-min N ...) -> (values fixnum fixnum)</procedure>
445
446Returns the maximum & minimum values for the {{fixnum}}s {{N ...}}.
447
448
449=== Math Constants (Module)
450
451==== Usage
452
453<enscript language=scheme>
454(require-extension mathh-consts)
455</enscript>
456
457==== Constants
458
459These are all {{flonum}}.
460
461; e : e
462; 1/e : 1/e
463; e^2 : e^2
464; e^pi/4 : e^(pi/4)
465; log2e : log2(e)
466; log10e : log10(e)
467; ln2 : log(2)
468; ln3 : ln(3)
469; lnpi : ln(pi)
470; ln10 : log(10)
471; 1/ln2 : 1/ln(2)
472; 1/ln10 : 1/ln(10)
473; pi : pi
474; pi/2 : pi/2
475; pi/4 : pi/4
476; 1/pi : 1/pi
477; 2/pi : 2/pi
478; 2/sqrtpi : 2/sqrt(pi)
479; sqrtpi : sqrt(pi)
480; pi^2 : pi^2
481; degree : pi/180
482; sqrt2 : sqrt(2)
483; 1/sqrt2 : 1/sqrt(2)
484; sqrt3 : sqrt(3)
485; sqrt5 : sqrt(5)
486; sqrt10 : sqrt(10)
487; cubert2 : cubert(2)
488; cubert3 : cubert(3)
489; 4thrt2 : fourthrt(2)
490; gamma1/2 : gamma(1/2)
491; gamma1/3 : gamma(1/3)
492; gamma2/3 : gamma(2/3)
493; phi : phi
494; lnphi : ln(phi)
495; 1/lnphi : 1/ln(phi)
496; euler : euler
497; e^euler : e^euler
498; sin1 : sin(1)
499; cos1 : cos(1)
500; zeta3 : theta(3)
501
502
503=== Math Constants (Include)
504
505Common constants, using 'define-constant'. As such they must be textually
506included.
507
508==== Usage
509
510<enscript language=scheme>
511(include "mathh-constants")
512</enscript>
513
514==== Constants
515
516; E : e
517; 1/E : 1/e
518; E^2 : e^2
519; E^PI/4 : e^(pi/4)
520; LOG2E : log2(e)
521; LOG10E : log10(e)
522; LN2 : log(2)
523; LN3 : ln(3)
524; LNPI : ln(pi)
525; LN10 : log(10)
526; 1/LN2 : 1/ln(2)
527; 1/LN10 : 1/ln(10)
528; PI : pi
529; PI/2 : pi/2
530; PI/4 : pi/4
531; 1/PI : 1/pi
532; 2/PI : 2/pi
533; 2/SQRTPI : 2/sqrt(pi)
534; SQRTPI : sqrt(pi)
535; PI^2 : pi^2
536; DEGREE : pi/180
537; SQRT2 : sqrt(2)
538; 1/SQRT2 : 1/sqrt(2)
539; SQRT3 : sqrt(3)
540; SQRT5 : sqrt(5)
541; SQRT10 : sqrt(10)
542; CUBERT2 : cubert(2)
543; CUBERT3 : cubert(3)
544; 4THRT2 : fourthrt(2)
545; GAMMA1/2 : gamma(1/2)
546; GAMMA1/3 : gamma(1/3)
547; GAMMA2/3 : gamma(2/3)
548; PHI : phi
549; LNPHI : ln(phi)
550; 1/LNPHI : 1/ln(phi)
551; EULER : euler
552; E^EULER : e^euler
553; SIN1 : sin(1)
554; COS1 : cos(1)
555; ZETA3 : theta(3)
556
557
558== Notes
559
560* The C library call {{gamma}} is deprecated in favor of {{tgamma}} but not
561available yet on some platforms, so we use {{gamma}} where necessary.
562
563* Some library calls that are not supplied by the platform have rough
564implementations supplied. See {{Bugs and Limitations}}.
565
566* The general naming convention is to use the C library call name as the Scheme
567name. But there are exceptions:
568
569; fmod : fpmod - ''fp-utils'' {{fpmodulo}} - should be in Chicken library?
570; j0 : bessel-j0 (Prefixed to distinguish the names from common variables)
571; j1 : bessel-j1
572; jn : bessel-jn
573; y0 : bessel-y0
574; y1 : bessel-y1
575; yn : bessel-yn
576
577
578== Bugs and Limitations
579
580* CHICKEN_INCLUDE_PATH must at least state the value of the
581{{(repository-path)}} to include ''mathh-constants.scm''. Suggest using the
582module ''mathh-consts''.
583
584* The types {{integer}} & {{real}} refer to the Chicken "core" concept of a
585number. Support for the full numeric tower is '''not''' provided.
586
587*  Windows library calls {{lgamma}}, {{gamma}}, {{acosh}}, {{asinh}},
588{{atanh}}, {{cbrt}} & {{signbit}} are not provided.
589
590* FreeBSD does not provide the library call {{log2}}. A usable {{log2}} is
591supplied.
592
593* The {{fpclass}} {{quiet-nan}} is only distinguished on Windows.
594
595* ''fx-utils.scm'' & ''fp-utils.scm'' belong in own eggs.
596
597
598== Author
599
600[[/users/kon-lovett|Kon Lovett]]
601[[/users/john cowan|John Cowan]]
602
603
604== Version history
605
606; 3.4.2 : Fix foreign-declare use. Fix {{fpzero?}}, {{fppositive?}}, {{fpnegative?}}, {{fpcardinal?}} again.
607; 3.4.1 : Remove unneeded dependency.
608; 3.4.0 ; Fix {{fppositive?}}, {{fpnegative?}}, {{fpcardinal?}}, {{fpeven?}}, {{fpodd?}}.
609; 3.3.3 ; Remove Windows {{log2}}, {{log1p}}, {{erf}}, {{erfc}}, {{scalbn}}.
610; 3.3.2 ;
611; 3.3.1 ;
612; 3.3.0 ; Add {{log-with-base}}. Deprecate {{make-log/base}}. Fix {{fprandom}} sign preservation.
613; 3.2.4 ; Add {{fxlog2}}, fix {{fxpow2log2}}.
614; 3.2.3 ; Fix {{4THRT2}}, {{1/LNPHI}}, extend {{1/SQRT2}}.
615; 3.2.2 ; Remove ''inline'' generation for mathh.
616; 3.2.1 ; Add types. Fix {{signbit}} & {{fpclass}}.
617; 3.2.0 ; Fix {{fpodd?}}. Add ''fx-utils.scm''. Extend ''fp-utils.scm''.
618; 3.1.0 ; Added module for ''mathh-constants.scm''.
619; 3.0.0 ; Moved copy of ''mathh-constants.scm'' to {{(chicken-home)}}. Ticket #1327
620; 2.2.6 ; better argvector chicken test
621; 2.2.5 ; argvector chicken support
622; 2.2.4 ;
623; 2.2.3 ; Fix for ticket #630
624; 2.2.2 ; ''mathh-constants.scm'' copied to Chicken Repository. Produces shared+static object files.
625; 2.2.1 : Better ''no-install'' support.
626; 2.2.0 : Added {{acosh}}, {{asinh}}, {{atanh}}, {{erf}} & {{erfc}}. Includes <sunmath.h> on Sun platform for {{log2}}.
627; 2.1.0 : Added {{signbit}}, {{copysign}}, {{nextafter}} & {{cbrt}}.
628; 2.0.0 : Chicken 4 release. {{fpclass}} and {{fpclassify}} are now part of the '''mathh''' extension.
629
630
631== License
632
633This code is in the public domain.
Note: See TracBrowser for help on using the repository browser.