Changes between Version 19 and Version 20 of FlonumsCowan


Ignore:
Timestamp:
09/15/16 17:05:50 (9 months ago)
Author:
cowan
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • FlonumsCowan

    v19 v20  
    55== Rationale == 
    66 
    7 Flonum arithmetic is already supported by many systems, mainly to remove type-dispatching overhead. Standardizing flonum arithmetic increases the portability of code that uses it. Standardizing the range 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 implementation-dependent. 
     7Flonum arithmetic is already supported by many systems, mainly to remove type-dispatching 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 implementation-dependent. 
    88 
    99The sources of the procedures in this SRFI are R7RS-small, [http://srfi.schemers.org/srfi-141/srfi-141.html SRFI 141], [http://www.r6rs.org/final/html/r6rs-lib/r6rs-lib-Z-H-12.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``.) 
    1010 
     11Scheme implementations that use IEEE 754 floating point numbers should follow the specifications of that standard. 
     12 
    1113== Specification == 
    1214 
    1315It 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 32-bit inexact number, and 12.0 is a 64-bit inexact number, they cannot both be flonums.  In this situation, it is recommended that the 64-bit numbers be flonums. 
    1416 
    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 non-real number, the result is `+nan.0` if the implementation supports that number, or an arbitrary flonum if not. 
     17It is an error, except as otherwise noted, for an argument not to be a flonum.  If the mathematically correct result is a non-real number, the result is `+nan.0` if the implementation supports that number, or an arbitrary flonum if not. 
     18 
     19Flonum 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. 
    1620 
    1721This SRFI uses ''x, y, z'' as 
    18 parameter names for flonum arguments, and ''ix, iy, iz'' 
    19 as a name for integer-valued flonum arguments, i.e., flonums for which the 
     22parameter names for flonum arguments, and ''ix'' 
     23as a name for an integer-valued flonum argument, i.e., a flonum for which the 
    2024`integer?` predicate returns true. 
    2125 
    2226=== Constants === 
    2327 
    24 The following C99 constants are provided as Scheme variables. 
     28The following (mostly C99) constants are provided as Scheme variables. 
    2529 
    2630`fl-e` 
    2731 
    28 Value of the mathematical constant ''e''.  (C99 `M_E`) 
     32Bound to the value of the mathematical constant ''e''.  (C99 `M_E`) 
    2933 
    3034`fl-log2-e` 
    3135 
    32 Value of `(fllog fl-e 2.0)`.  (C99 `M_LOG2E`) 
     36Bound to the value of `(fllog fl-e 2.0)`.  (C99 `M_LOG2E`) 
    3337 
    3438`fl-log10-e` 
    3539 
    36 Value of `(fllog fl-e 10.0)`.  (C99 `M_LOG10E`) 
     40Bound to the value of `(fllog fl-e 10.0)`.  (C99 `M_LOG10E`) 
    3741 
    3842`fl-ln-2` 
    3943 
    40 Value of `(fllog 2.0)`  (C99 `M_LN2`) 
     44Bound to the value of `(fllog 2.0)`  (C99 `M_LN2`) 
    4145 
    4246`fl-ln-10` 
    4347 
    44 Value of `(fllog 10.0)`  (C99 `M_LN10`) 
     48Bound to the value of `(fllog 10.0)`  (C99 `M_LN10`) 
    4549 
    4650`fl-pi` 
    4751 
    48 Value of the mathematical constant π.  (C99 `M_PI`) 
     52Bound to the value of the mathematical constant π.  (C99 `M_PI`) 
    4953 
    5054`fl-pi/2` 
    5155 
    52 Value of `(fl/ fl-pi 2.0)`  (C99 `M_PI_2`) 
     56Bound to the value of `(fl/ fl-pi 2.0)`  (C99 `M_PI_2`) 
    5357 
    5458`fl-pi/4` 
    5559 
    56 Value of `(fl/ fl-pi 4.0)`  (C99 `M_PI_4`) 
     60Bound to the value of `(fl/ fl-pi 4.0)`  (C99 `M_PI_4`) 
    5761 
    5862`fl-1/pi` 
    5963 
    60 Value of `(fl/ 1.0 fl-pi)`.  (C99 `M_1_PI`) 
     64Bound to the value of `(fl/ 1.0 fl-pi)`.  (C99 `M_1_PI`) 
    6165 
    6266`fl-2/pi` 
    6367 
    64 Value of `(fl/ 2.0 fl-pi)`.  (C99 `M_2_PI`) 
     68Bound to the value of `(fl/ 2.0 fl-pi)`.  (C99 `M_2_PI`) 
    6569 
    6670`fl-2/sqrt-pi` 
    6771 
    68 Value of `(fl/ 2.0 (flsqrt fl-pi))`.  (C99 `M_2_SQRTPI`) 
     72Bound to the value of `(fl/ 2.0 (flsqrt fl-pi))`.  (C99 `M_2_SQRTPI`) 
    6973 
    7074`fl-sqrt-2` 
    7175 
    72 Value of `(flsqrt 2.0)`.  (C99 `M_SQRT2`) 
     76Bound to the value of `(flsqrt 2.0)`.  (C99 `M_SQRT2`) 
    7377 
    7478`fl-1/sqrt-2` 
    7579 
    76 Value of `(fl/ 1,0 (flsqrt 2.0))`.  (C99 `M_SQRT1_2`) 
     80Bound to the value of `(fl/ 1,0 (flsqrt 2.0))`.  (C99 `M_SQRT1_2`) 
    7781 
    7882`fl-maximum` 
    7983 
    80 Value of the largest finite flonum. 
    81  
    82 `fl-fast-multiply-add` 
    83  
    84 Equal 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`) 
     84Bound to the value of the largest finite flonum. 
     85 
     86`fl-fast-+*` 
     87 
     88Bound 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`) 
    8589 
    8690`fl-integer-exponent-zero` 
    8791 
    88 Value of `(flinteger-binary-log 0)`.  (C99 `FP_ILOGB0`) 
     92Bound to whatever value is returned by `(flinteger-binary-log 0)`.  (C99 `FP_ILOGB0`) 
    8993 
    9094`fl-integer-exponent-nan` 
    9195 
    92 Value of `(flinteger-binary-log +0.nan)`.  (C99 `FP_ILOGBNAN`) 
     96Bound to whatever value is returned by `(flinteger-binary-log +0.nan)`.  (C99 `FP_ILOGBNAN`) 
    9397 
    9498`fl-radix` 
     
    140144`(fleven? `''ix''`)` 
    141145 
    142 `(flfinite? `''ix''`)` 
    143  
    144 `(flinfinite? `''ix''`)` 
    145  
    146 `(flnan? `''ix''`)` 
     146`(flfinite? `''x''`)` 
     147 
     148`(flinfinite? `''x''`)` 
     149 
     150`(flnan? `''x''`)` 
    147151 
    148152These 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. 
    149153 
    150 Note that `(flnegative? -0.0)<` must return `#f`; 
     154Note that `(flnegative? -0.0)` must return `#f`; 
    151155otherwise it would lose the correspondence with 
    152156`(fl< -0.0 0.0)`, which is `#f` 
     
    161165Return the flonum sum or product of their flonum 
    162166arguments.  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.) 
     167approximates the mathematical sum or product. 
    166168 
    167169`(fl+* `''x y z''`)` 
     
    181183In general, they 
    182184should 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 well-defined by the IEEE standards. 
     185difference or quotient. 
    188186 
    189187`(flmax `''x'' ...`)` 
     
    201199`(flabsdiff `''x y''`)` 
    202200 
    203 Returns `(flabs (fl- x y))`.  (C99 `fdim`) 
     201Returns `(flabs (fl- x y))` without internal overflow.  (C99 `fdim`) 
    204202 
    205203`(flsgn `''x''`)` 
     
    211209`(fldenominator `''x''`)` 
    212210 
    213 Returns the numerator/enominator of ``x`` 
    214 as a flonum; the result is computed as if <i>x</i> was represented as 
     211Returns the numerator/denominator of ''x'' 
     212as a flonum; the result is computed as if ''x'' was represented as 
    215213a fraction in lowest terms.  The denominator is always positive.  The 
    216214denominator of 0.0 is defined to be 1.0. 
     
    225223 
    226224These procedures return integral flonums for flonum arguments that are 
    227 not infinities or NaNs.  For such arguments, `flfloor` returns the 
     225not infinities or !NaNs.  For such arguments, `flfloor` returns the 
    228226largest integral flonum not larger than ''x''.  The `flceiling` 
    229227procedure 
     
    235233 
    236234 
    237 Although infinities and NaNs are not integers, these procedures return 
     235Although infinities and !NaNs are not integers, these procedures return 
    238236an infinity when given an infinity as an argument, and a NaN when 
    239237given a NaN. 
     
    251249flexp 
    252250fl2exp  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 floating-point value, for non-zero x, where r is the radix of the machine's floating-point arithmetic 
    255 flfraction-exponent     double modf(double, double *)   returns two values, fraction and int exponent 
     251flexponent      double logb(double x)   the exponent of x, 
     252which is the integral part of 
     253log_r(|x|), as a signed floating-point value, for non-zero x, 
     254where r is the radix of the machine's floating-point arithmetic 
     255flfraction-exponent     double modf(double, double * 
     256returns two values, fraction and int exponent 
    256257flinteger-exponent      int ilogb(double)       binary log as int 
    257258fllog 
     
    261262flnormalized-fraction-exponent  double frexp(double, int *) 
    262263returns 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 
     264flscalbn        double scalbn(double x, int y)  x*ry, 
     265where r is the machine float radix 
    264266}}} 
    265267 
     
    267269`flsqrt` should return -0.0. 
    268270 
    269 The `flexpt` procedure returns ''x'' raised to the power 'y'' 
     271The `flexpt` procedure returns ''x'' raised to the power ''y'' 
    270272if ''x'' is non-negative or ''y'' is an integral flonum.  If ''x'' is 
    271273negative and ''y'' is not an integer, the result may be a 
     
    299301`(flatanh `''x''`)`  (C99 `atanh`) 
    300302 
    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 floating-point arithmetic  
    303 should follow the relevant standards for these procedures. 
     303These are the usual trigonometric functions. The `flatan` function, when passed two arguments, returns `(flatan (/ y x))` without requiring the use of complex numbers. 
    304304 
    305305`(flremquo `''x y''`)` 
     
    326326=== Special functions === 
    327327 
    328 ||Scheme name||C signature||Comments|| 
    329 ||`flcomplementary-error-function`||`double      erfc(double)`||-|| 
    330 ||`flerror-function`||`double      erf(double)`||-|| 
    331 ||`flfirst-bessel`||`double      jn(int n, double)`||bessel function of the first kind, order n|| 
    332 ||`flgamma`||`double      tgamma(double)`||-|| 
    333 ||`fllog-gamma`||`double      lgamma(double)`||returns two values, log(|gamma(x)|) and sgn(gamma(x))|| 
    334 ||`flsecond-bessel`||`double      yn(int n, double)`||bessel function of the second kind, order ''n''|| 
    335  
    336  
    337  
    338  
     328`(flgamma `''x''`)` 
     329 
     330Returns Γ(''x''), the gamma function applied to ''x''.  This is equal to (''x''-1)! for 
     331integers.  (C99 `tgamma`) 
     332 
     333`(flloggamma `''x''`)` 
     334 
     335Returns two values, log Γ(|''x''|) without internal overflow, and sgn(Γ(''x'')).  (C99 `lgamma`) 
     336 
     337`(first-bessel `''x n''`)` 
     338 
     339Returns the ''n''th order Bessel function of the first kind applied to ''x'', J,,n,,(x).  (C99 `j0`, `j1`, `jn`) 
     340 
     341`(second-bessel `''x n''`)` 
     342 
     343Returns 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 
     347Returns the error function erf(''x'').  (C99 `erf`) 
     348 
     349`(erfc `''x''`)` 
     350 
     351Returns the complementary error function, `(- 1 (erf x))`.  (C99 `erfc`)