Changes between Version 19 and Version 20 of FlonumsCowan
 Timestamp:
 09/15/16 17:05:50 (8 months ago)
Legend:
 Unmodified
 Added
 Removed
 Modified

FlonumsCowan
v19 v20 5 5 == Rationale == 6 6 7 Flonum arithmetic is already supported by many systems, mainly to remove typedispatching overhead. Standardizing flonum arithmetic increases the portability of code that uses it. Standardizing the range o f flonums would make flonum operations inefficient on some systems, which would defeat their purpose. Therefore, this SRFI specifies some of the semantics of flonums, but makes the rangeimplementationdependent.7 Flonum arithmetic is already supported by many systems, mainly to remove typedispatching overhead. Standardizing flonum arithmetic increases the portability of code that uses it. Standardizing the range or precision of flonums would make flonum operations inefficient on some systems, which would defeat their purpose. Therefore, this SRFI specifies some of the semantics of flonums, but makes the range and precision implementationdependent. 8 8 9 9 The sources of the procedures in this SRFI are R7RSsmall, [http://srfi.schemers.org/srfi141/srfi141.html SRFI 141], [http://www.r6rs.org/final/html/r6rslib/r6rslibZH12.html#node_sec_11.3 the R6RS flonum library], and the [http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/math.h.html C99/Posix library] `<math.h>`, which should be available directly or indirectly to Scheme implementers. (The C90 version of `<math.h>` lacks ``arcsinh``, ``arccosh``, ``arctanh``, ``erf``, and ``tgamma``.) 10 10 11 Scheme implementations that use IEEE 754 floating point numbers should follow the specifications of that standard. 12 11 13 == Specification == 12 14 13 15 It is required that if two flonums are equal in the sense of `=`, they are also equal in the sense of `eqv?`. That is, if 12.0f0 is a 32bit inexact number, and 12.0 is a 64bit inexact number, they cannot both be flonums. In this situation, it is recommended that the 64bit numbers be flonums. 14 16 15 Flonum operations must be at least as accurate as their generic counterparts applied to flonum arguments. It is an error, except as otherwise noted, for an argument not to be a flonum. In some cases, operations should be more accurate than their naive generic expansions because they have a smaller total roundoff error. If the generic result is a nonreal number, the result is `+nan.0` if the implementation supports that number, or an arbitrary flonum if not. 17 It is an error, except as otherwise noted, for an argument not to be a flonum. If the mathematically correct result is a nonreal number, the result is `+nan.0` if the implementation supports that number, or an arbitrary flonum if not. 18 19 Flonum operations must be at least as accurate as their generic counterparts applied to flonum arguments. In some cases, operations should be more accurate than their naive generic expansions because they have a smaller total roundoff error. 16 20 17 21 This SRFI uses ''x, y, z'' as 18 parameter names for flonum arguments, and ''ix , iy, iz''19 as a name for integervalued flonum arguments, i.e., flonumsfor which the22 parameter names for flonum arguments, and ''ix'' 23 as a name for an integervalued flonum argument, i.e., a flonum for which the 20 24 `integer?` predicate returns true. 21 25 22 26 === Constants === 23 27 24 The following C99constants are provided as Scheme variables.28 The following (mostly C99) constants are provided as Scheme variables. 25 29 26 30 `fle` 27 31 28 Value of the mathematical constant ''e''. (C99 `M_E`)32 Bound to the value of the mathematical constant ''e''. (C99 `M_E`) 29 33 30 34 `fllog2e` 31 35 32 Value of `(fllog fle 2.0)`. (C99 `M_LOG2E`)36 Bound to the value of `(fllog fle 2.0)`. (C99 `M_LOG2E`) 33 37 34 38 `fllog10e` 35 39 36 Value of `(fllog fle 10.0)`. (C99 `M_LOG10E`)40 Bound to the value of `(fllog fle 10.0)`. (C99 `M_LOG10E`) 37 41 38 42 `flln2` 39 43 40 Value of `(fllog 2.0)` (C99 `M_LN2`)44 Bound to the value of `(fllog 2.0)` (C99 `M_LN2`) 41 45 42 46 `flln10` 43 47 44 Value of `(fllog 10.0)` (C99 `M_LN10`)48 Bound to the value of `(fllog 10.0)` (C99 `M_LN10`) 45 49 46 50 `flpi` 47 51 48 Value of the mathematical constant π. (C99 `M_PI`)52 Bound to the value of the mathematical constant π. (C99 `M_PI`) 49 53 50 54 `flpi/2` 51 55 52 Value of `(fl/ flpi 2.0)` (C99 `M_PI_2`)56 Bound to the value of `(fl/ flpi 2.0)` (C99 `M_PI_2`) 53 57 54 58 `flpi/4` 55 59 56 Value of `(fl/ flpi 4.0)` (C99 `M_PI_4`)60 Bound to the value of `(fl/ flpi 4.0)` (C99 `M_PI_4`) 57 61 58 62 `fl1/pi` 59 63 60 Value of `(fl/ 1.0 flpi)`. (C99 `M_1_PI`)64 Bound to the value of `(fl/ 1.0 flpi)`. (C99 `M_1_PI`) 61 65 62 66 `fl2/pi` 63 67 64 Value of `(fl/ 2.0 flpi)`. (C99 `M_2_PI`)68 Bound to the value of `(fl/ 2.0 flpi)`. (C99 `M_2_PI`) 65 69 66 70 `fl2/sqrtpi` 67 71 68 Value of `(fl/ 2.0 (flsqrt flpi))`. (C99 `M_2_SQRTPI`)72 Bound to the value of `(fl/ 2.0 (flsqrt flpi))`. (C99 `M_2_SQRTPI`) 69 73 70 74 `flsqrt2` 71 75 72 Value of `(flsqrt 2.0)`. (C99 `M_SQRT2`)76 Bound to the value of `(flsqrt 2.0)`. (C99 `M_SQRT2`) 73 77 74 78 `fl1/sqrt2` 75 79 76 Value of `(fl/ 1,0 (flsqrt 2.0))`. (C99 `M_SQRT1_2`)80 Bound to the value of `(fl/ 1,0 (flsqrt 2.0))`. (C99 `M_SQRT1_2`) 77 81 78 82 `flmaximum` 79 83 80 Value of the largest finite flonum.81 82 `flfast multiplyadd`83 84 Equalto `#t` if `(fl+* x y z)` is known to be faster than `(fl+ (fl* x y) z), or `#f` otherwise. (C99 `FP_FAST_FMA`)84 Bound to the value of the largest finite flonum. 85 86 `flfast+*` 87 88 Bound to `#t` if `(fl+* x y z)` is known to be faster than `(fl+ (fl* x y) z), or `#f` otherwise. (C99 `FP_FAST_FMA`) 85 89 86 90 `flintegerexponentzero` 87 91 88 Value of`(flintegerbinarylog 0)`. (C99 `FP_ILOGB0`)92 Bound to whatever value is returned by `(flintegerbinarylog 0)`. (C99 `FP_ILOGB0`) 89 93 90 94 `flintegerexponentnan` 91 95 92 Value of`(flintegerbinarylog +0.nan)`. (C99 `FP_ILOGBNAN`)96 Bound to whatever value is returned by `(flintegerbinarylog +0.nan)`. (C99 `FP_ILOGBNAN`) 93 97 94 98 `flradix` … … 140 144 `(fleven? `''ix''`)` 141 145 142 `(flfinite? `'' ix''`)`143 144 `(flinfinite? `'' ix''`)`145 146 `(flnan? `'' ix''`)`146 `(flfinite? `''x''`)` 147 148 `(flinfinite? `''x''`)` 149 150 `(flnan? `''x''`)` 147 151 148 152 These numerical predicates test a flonum for a particular property, returning `#t` or `#f`. The `flinteger?` procedure tests whether the flonum is an integer, `flzero?` tests whether it is `fl=?` to zero, `flpositive?` tests whether it is greater than zero, `flnegative?` tests whether it is less than zero, `flodd?` tests whether it is odd, `fleven?` tests whether it is even, `flfinite?` tests whether it is not an infinity and not a NaN, `flinfinite?` tests whether it is an infinity, and `flnan?` tests whether it is a NaN. 149 153 150 Note that `(flnegative? 0.0) <` must return `#f`;154 Note that `(flnegative? 0.0)` must return `#f`; 151 155 otherwise it would lose the correspondence with 152 156 `(fl< 0.0 0.0)`, which is `#f` … … 161 165 Return the flonum sum or product of their flonum 162 166 arguments. In general, they should return the flonum that best 163 approximates the mathematical sum or product. (For implementations 164 that represent flonums using IEEE binary floating point, the 165 meaning of "best" is defined by the IEEE standards.) 167 approximates the mathematical sum or product. 166 168 167 169 `(fl+* `''x y z''`)` … … 181 183 In general, they 182 184 should return the flonum that best approximates the mathematical 183 difference or quotient. For undefined quotients, `fl/` 184 behaves as specified by the 185 IEEE standards. For implementations that represent flonums 186 using IEEE binary floating point, the meaning of "best" is 187 reasonably welldefined by the IEEE standards. 185 difference or quotient. 188 186 189 187 `(flmax `''x'' ...`)` … … 201 199 `(flabsdiff `''x y''`)` 202 200 203 Returns `(flabs (fl x y))` . (C99 `fdim`)201 Returns `(flabs (fl x y))` without internal overflow. (C99 `fdim`) 204 202 205 203 `(flsgn `''x''`)` … … 211 209 `(fldenominator `''x''`)` 212 210 213 Returns the numerator/ enominator of ``x``214 as a flonum; the result is computed as if <i>x</i>was represented as211 Returns the numerator/denominator of ''x'' 212 as a flonum; the result is computed as if ''x'' was represented as 215 213 a fraction in lowest terms. The denominator is always positive. The 216 214 denominator of 0.0 is defined to be 1.0. … … 225 223 226 224 These procedures return integral flonums for flonum arguments that are 227 not infinities or NaNs. For such arguments, `flfloor` returns the225 not infinities or !NaNs. For such arguments, `flfloor` returns the 228 226 largest integral flonum not larger than ''x''. The `flceiling` 229 227 procedure … … 235 233 236 234 237 Although infinities and NaNs are not integers, these procedures return235 Although infinities and !NaNs are not integers, these procedures return 238 236 an infinity when given an infinity as an argument, and a NaN when 239 237 given a NaN. … … 251 249 flexp 252 250 fl2exp double ldexp(double x, int n) x*2n 253 flexponent double logb(double x) the exponent of x, which is the integral part of 254 log_r(x), as a signed floatingpoint value, for nonzero x, where r is the radix of the machine's floatingpoint arithmetic 255 flfractionexponent double modf(double, double *) returns two values, fraction and int exponent 251 flexponent double logb(double x) the exponent of x, 252 which is the integral part of 253 log_r(x), as a signed floatingpoint value, for nonzero x, 254 where r is the radix of the machine's floatingpoint arithmetic 255 flfractionexponent double modf(double, double * 256 returns two values, fraction and int exponent 256 257 flintegerexponent int ilogb(double) binary log as int 257 258 fllog … … 261 262 flnormalizedfractionexponent double frexp(double, int *) 262 263 returns two values, fraction in range [1/2,1) and int exponent 263 flscalbn double scalbn(double x, int y) x*ry, where r is the machine float radix 264 flscalbn double scalbn(double x, int y) x*ry, 265 where r is the machine float radix 264 266 }}} 265 267 … … 267 269 `flsqrt` should return 0.0. 268 270 269 The `flexpt` procedure returns ''x'' raised to the power ' y''271 The `flexpt` procedure returns ''x'' raised to the power ''y'' 270 272 if ''x'' is nonnegative or ''y'' is an integral flonum. If ''x'' is 271 273 negative and ''y'' is not an integer, the result may be a … … 299 301 `(flatanh `''x''`)` (C99 `atanh`) 300 302 301 These are the usual trigonometric functions. Note that if the result is not a real number, `+nan.0` is returned if available, or if not, an arbitrary flonum. The `flatan` function, when passed two arguments, returns `(flatan (/ y x))` without requiring the use of complex numbers. 302 Implementations that use IEEE binary floatingpoint arithmetic 303 should follow the relevant standards for these procedures. 303 These are the usual trigonometric functions. The `flatan` function, when passed two arguments, returns `(flatan (/ y x))` without requiring the use of complex numbers. 304 304 305 305 `(flremquo `''x y''`)` … … 326 326 === Special functions === 327 327 328 Scheme nameC signatureComments 329 `flcomplementaryerrorfunction``double erfc(double)` 330 `flerrorfunction``double erf(double)` 331 `flfirstbessel``double jn(int n, double)`bessel function of the first kind, order n 332 `flgamma``double tgamma(double)` 333 `flloggamma``double lgamma(double)`returns two values, log(gamma(x)) and sgn(gamma(x)) 334 `flsecondbessel``double yn(int n, double)`bessel function of the second kind, order ''n'' 335 336 337 338 328 `(flgamma `''x''`)` 329 330 Returns Γ(''x''), the gamma function applied to ''x''. This is equal to (''x''1)! for 331 integers. (C99 `tgamma`) 332 333 `(flloggamma `''x''`)` 334 335 Returns two values, log Γ(''x'') without internal overflow, and sgn(Γ(''x'')). (C99 `lgamma`) 336 337 `(firstbessel `''x n''`)` 338 339 Returns the ''n''th order Bessel function of the first kind applied to ''x'', J,,n,,(x). (C99 `j0`, `j1`, `jn`) 340 341 `(secondbessel `''x n''`)` 342 343 Returns the ''n''th order Bessel function of the second kind applied to ''x'', Y,,n,,(x). (C99 `y0`, `y1`, `yn`) 344 345 `(erf `''x''`)` 346 347 Returns the error function erf(''x''). (C99 `erf`) 348 349 `(erfc `''x''`)` 350 351 Returns the complementary error function, `( 1 (erf x))`. (C99 `erfc`)