source: project/wiki/eggref/4/numbers @ 26634

Last change on this file since 26634 was 26634, checked in by sjamaan, 9 years ago

Update numbers changelog for 2.8

File size: 10.9 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== Synopsis
5
6Support for the full numeric tower.
7
8== Interface
9
10This extension provides support for large exact integers, exact rational and
11complex numbers.
12
13The following standard procedures are redefined:
14
15 +     -      *     /
16 =     >      <     >=    <=
17 abs   max    min
18 eqv?  equal?
19 exp   expt   log   sin   cos   tan   atan   asin   acos   sqrt
20 quotient     modulo      remainder
21 exact?       inexact?
22 exact->inexact           inexact->exact
23 positive?    negative?   even?       odd?   zero?
24 number?      complex?    real?       rational?     integer?
25 gcd   lcm
26 truncate     ceiling     floor       round
27 number->string           string->number
28 numerator    denominator
29 rationalize
30 magnitude         angle
31 real-part         imag-part
32
33The following standard procedures are provided:
34
35 make-rectangular  make-polar
36
37The following non-standard extended procedures are redefined:
38
39 add1         sub1
40 signum
41 bitwise-and  bitwise-ior  bitwise-xor  bitwise-not  arithmetic-shift
42 randomize    random       finite?
43
44Additionally the following procedures are available:
45
46<procedure>(infinite? Z)</procedure>
47
48Is the number {{Z}} {{+inf.0}} or {{-inf.0}}, or a complex number
49containing either infinity as its real or imaginary part?
50
51'''Note''': This is '''not''' the inverse of {{finite?}}, since it
52produces {{#f}} on {{nan.0}} (or complex numbers containing {{nan.0}}),
53while {{finite?}} also returns {{#f}} in that case.
54
55<procedure>(nan? Z)</procedure>
56
57Is the object {{Z}} a real representing {{nan.0}}?
58
59<procedure>(exact-integer-sqrt K)</procedure>
60
61Returns two values {{s}} and {{r}}, where {{s^2 + r = K}} and {{K < (s+1)^2}}.
62In other words, {{s}} is the closest square root we can find that's equal to or
63smaller than {{K}}, and {{r}} is the rest if {{K}} isn't a neat square of two numbers.
64
65<procedure>(exact-integer-nth-root K N)</procedure>
66
67Like {{exact-integer-sqrt}}, but with any base value.  Calculates
68{{\sqrt[N]{K}}}, the {{N}}th root of {{K}} and returns two values
69{{s}} and {{r}} where {{s^N + r = K}} and {{K < (s+1)^N}}.
70
71<procedure>(exact-integer? X)</procedure>
72
73Is {{X}} an exact integer?
74
75<procedure>(quotient&remainder A B)</procedure>
76
77Return the quotient ''and'' the remainder of A divided by B.
78
79This is especially useful for bignums, since both numbers are
80derived simultaneously.  This saves performing the division
81algorithm twice.
82
83<procedure>(quotient&modulo A B)</procedure>
84
85Like {{quotient&remainder}}, except return the modulo instead of remainder.
86
87<procedure>(conj Z)</procedure>
88
89Returns the conjugate of the complex number Z.
90
91<procedure>(bignum? X)</procedure>
92
93Is X an extended-precision integer?
94
95<procedure>(ratnum? X)</procedure>
96
97Is X a ratio?
98
99<procedure>(cplxnum? X)</procedure>
100
101Is X a complex?
102
103<procedure>(rectnum? X)</procedure>
104
105Is X an exact-complex? (Treats an integer-floatingpoint as "exact".)
106
107<procedure>(compnum? X)</procedure>
108
109Is X an inexact-complex?
110
111<procedure>(cflonum? X)</procedure>
112
113Is X a floatingpoint-complex or a floatingpoint?
114
115<procedure>(cintnum? X)</procedure>
116
117Is X an integer-complex or an integer?
118
119<procedure>(integer-length X)</procedure>
120
121From [[http://srfi.schemers.org/srfi-60|SRFI-60]]; get the number of bits
122required to represent the integer {{X}} in 2s complement notation.
123
124== Example
125
126<enscript highlight=scheme>
127(define (fac n)
128  (if (zero? n)
129      1
130      (* n (fac (- n 1))) ) ) ) )
131
132(fac 100)   
133; => 9332621544394415268169923885626670049071596826438162146859296389
134     5217599993229915608941463976156518286253697920827223758251185210
135     916864000000000000000000000000
136</enscript>
137
138== Compiled code
139
140Starting with version 2.8, extended number literals can be used in compiled code.  To make this work, compile your code with:
141
142  csc -X numbers-syntax foo.scm
143
144'''IMPORTANT''': This only works when the code will be run on exactly the same platform as the Scheme compiler ran on.  Cross-compilation and compiling to C and compiling that on the target platform is ''not supported''. (You will get an error message when you try to do it anyway)
145
146== Bugs and limitations
147
148* Extended number literals can not be used portably in compiled code (use {{string->number}} for maximum portability).
149* For best results, use Chicken 4.7.4 or later.  Extended numbers syntax isn't reliably supported by the reader of earlier Chicken versions (here as well, use {{string->number}} for maximum portability).
150
151== About this egg
152
153=== Author
154
155[[http://wiki.call-cc.org/felix%20winkelmann|felix]]
156
157The code for complex arithmetic was mostly taken from Thomas Chust's [[/eggref/3/complex|complex]] egg.
158
159=== Maintainer
160
161The CHICKEN Team
162
163=== Version history
164
165; 2.8: Correct handling of exactness prefix (requires recent Chicken to work, at least 4.7.4). Division by inexact zero is no longer considered an error, but returns NaN or +Inf/-Inf.  {{inexact->exact}} raises an error on NaN instead of returning 0 (reported by Felix Winkelmann).  Fix {{log}} so it doesn't erroneously fail on complex numbers.  Generalize {{asin}} and {{acos}} so they can return complex numbers. Fix {{<=}} and {{>=}} so they work when given a {{nan}} argument in rest position. Various fixes for code that expected inexact numbers so it calls {{exact->inexact}} before. Add types database for scrutinizer (Only in Chicken 4.7.4 and later).
166; 2.7: Fix several bugs ({{expt}}, {{integer?}}, {{rational?}}, {{<=}}, {{>=}}, {{eqv?}}, {{-}}) found by importing the number tests from Gauche and writing an extensive test for number syntax edge cases. Complete rewrite of number parser (it should fully conform to the R7RS superset of R5RS number syntax now).  Dropped dependency on the regex egg.  Improved precision of {{exact->inexact}} so it can handle more extreme numbers. Provide the {{nan?}}, {{finite?}} and {{infinite?}} predicates and {{integer-length}} procedure.
167; 2.6.1: Fix {{string->number}} so it raises an exception instead of crashing when passed a negative, zero or too large base (reported by Peter Hendrickson).  Update test scripts so they exit with nonzero status in case of failed tests (reported by Mario Goulart)
168; 2.6 : Fix expt and log so they work for numbers which produce complex results.
169; 2.5 : Fix expt so it doesn't use flonums and loses precision in case of bignums
170; 2.4 : Added regex to dependency list
171; 2.3 : Added regex requirement to make it work in Chicken 4.6.2+
172; 2.2 : Fixed ratnum normalization in case of negative divisors
173; 2.1 : Changed {{quotient}}, {{remainder}} and {{quotient&remainder}} semantics so they accept fractional flonums to match Chicken's implementation of {{quotient}} and {{remainder}}.  This also affects {{modulo}} and {{quotient&modulo}}.
174; 2.0 : Removed dependency on GMP, replacing it by the Scheme48 numbers code. Improved performance by integrating with GC.  Added benchmarks and more tests. Converted testsuite to use the [[/eggref/4/test|test]] egg instead of [[/eggref/4/testeez|testeez]]. [by Peter Bex]
175; 1.82 : removed dependency on [[/eggref/4/easyffi|easyffi]] (Thanks to Peter Bex)
176; 1.81 : fixed dependencies
177; 1.809 : Fix for {{(expt <number> <ratio>)}}, would fail [Bug noted by John Cowan]
178; 1.808 : Fix for 1.0+1i not treated as a rectnum or compnum [Bug noted by John Cowan] Added 'cintnum?' & 'cplxnum?' [kon lovett]
179; 1.806 : Fix for equal? when given keywords as args [Bug noted by papasi] [elf]
180; 1.804 : Using more accurate exact->inexact conversion for rationals [Alex Shinn]
181; 1.803 : fixed bug in fixnum bitwise operations [Thanks to Jeremy Sydik]
182; 1.802 : not quite complete support for static linking
183; 1.801 : Fixed a bug in {{angle}} [zb, mario]
184; 1.8 : Single-argument {{+}} and {{*}} didn't check argument type [Thanks to Stephen Gilardi]
185; 1.701 : Bugfix for compiler macros, undefined symbol [Kon Lovett]
186; 1.7 : Added compiler macros for {{bitwise-...}} operations
187; 1.6 : Compiler macros now work without -X numbers
188; 1.5 : Added support for speculative inlining of fixnum ops
189; 1.4 : Fixed bug in ratnum/bignum division [Thanks to Ivan Shmakov]
190; 1.3 : Fixing round for rational numbers [Alex Shinn]
191; 1.2 : Added {{bignum? ratnum? cflonum? rectnum? compnum?}} [Kon Lovett]
192; 1.1 : Uses easyffi properly [reported by John Cowan]
193; 1.0 : Fix for fixnum/rational comparison [by Zbigniew]
194; 0.999 : {{rational?}} always returned false for flonums
195; 0.998 : Added some missing definitions to numbers.scm [found by Kon Lovett]
196; 0.997 : Fixed memory leak in some bitwise operations [found by Dan Muresan]
197; 0.996 : Fixed a bug in {{expt}} [Daishi Kato]
198; 0.995 : {{round}} rounds to even (as specified by R5RS) [Thanks to Benedikt Rosenau]
199; 0.994 : Reimplemented {{=}} in C
200; 0.993 : Fixed {{equal?}} which didn't handle extended numbers nested in other data
201; 0.992 : Slight performance tuning for {{expt}} [Again by Daishi]
202; 0.991 : Fixed bug in fixnum/bignum subtraction [Thanks to Daishi Kato and Alex Shinn]
203; 0.99 : Speed improvements for {{expt}} by Daishi Kato
204; 0.98 : Added {{random}} and {{randomize}} [Suggested by Daishi Kato]
205; 0.97 : bignum/fixnum subtraction used wrong argument order [Thanks to Kon Lovett]
206; 0.96 : Several bug fixes by Alex Shinn; {{signum}} is exactness preserving
207; 0.95 : Alex Shinn contributed a working version of {{expt}}
208; 0.94 : Yet another bug-fix by Michal
209; 0.93 : Several bug-fixes by Michal Janeczek
210; 0.92 : exactness handling of {{expt}} is slightly better but still not perfect.
211; 0.91 : Fixed bug in {{integer?}}
212; 0.9 : (beta)
213
214=== License
215
216 Copyright (c) 2008-2012 The CHICKEN Team
217 Copyright (c) 2000-2007, Felix L. Winkelmann
218 Copyright (c) 1993-2008 Richard Kelsey and Jonathan Rees
219 Copyright 1986,1987,1988,1989,1990,1991 Massachusetts Institute of Technology
220 Copyright 1992,1993,1994,2004 Massachusetts Institute of Technology
221 All rights reserved.
222 
223 Redistribution and use in source and binary forms, with or without
224 modification, are permitted provided that the following conditions
225 are met:
226 1. Redistributions of source code must retain the above copyright
227    notice, this list of conditions and the following disclaimer.
228 2. Redistributions in binary form must reproduce the above copyright
229    notice, this list of conditions and the following disclaimer in the
230    documentation and/or other materials provided with the distribution.
231 3. The name of the authors may not be used to endorse or promote products
232    derived from this software without specific prior written permission.
233 
234 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
235 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
236 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
237 IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
238 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
239 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
240 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
241 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
242 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
243 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.