[[tags: egg]]

[[toc:]]

== SRFI 144: Flonums

=== Abstract

This SRFI describes numeric procedures applicable to flonums, a subset of the
inexact real numbers provided by a Scheme implementation. In most Schemes, the
flonums and the inexact reals are the same. These procedures are semantically
equivalent to the corresponding generic procedures, but allow more efficient
implementations.

=== Rationale

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 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. However,
this SRFI, unlike C99, does assume that the floating-point radix is 2.

The source of most of the variables and procedures in this SRFI is the
C99/Posix {{<math.h>}} library, which should be available directly or
indirectly to Scheme implementers. (Note: the C90 version of {{<math.h>}} lacks
{{arcsinh}}, {{arccosh}}, {{arctanh}}, {{erf}}, and {{tgamma}}.)

In addition, some procedures and variables are provided from the R6RS flonum
library, the Chicken flonum routines, and the Chicken mathh egg. Lastly, a few
procedures are flonum versions of R7RS-small numeric procedures.

The SRFI text is by John Cowan; the portable implementation is by Will Clinger.

=== Specification

It is required that all flonums have the same range and precision. 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.

When a C99 variable, procedure, macro, or operator is specified for a procedure
in this SRFI, the semantics of the Scheme variable or procedure are the same as
its C equivalent. The definitions given here of such procedures are informative
only; for precise definitions, users and implementers must consult the Posix or
C99 standards. This applies particularly to the behavior of these procedures on
{{-0.0}}, {{+inf.0}}, {{-inf.0}}, and {{+nan.0}}. However, conformance to this
SRFI does not require that these numbers exist or are flonums.

When a variable is bound to, or a procedure returns, a mathematical expression,
it is understood that the value is the best flonum approximation to the
mathematically correct value.

It is an error, except as otherwise noted, for an argument not to be a flonum.
If the mathematically correct result is not a real number, the result is
{{+nan.0}} if the implementation supports that number, or an arbitrary flonum
if not.

Flonum operations must be at least as accurate as their generic counterparts
when 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.

This SRFI uses {{x}}, {{y}}, {{z}} as parameter names for flonum arguments.
Exact integer parameters are designated {{n}}.

==== Mathematical Constants

The following (mostly C99) constants are provided as Scheme variables.

<constant>fl-e</constant>

Bound to the mathematical constant ''e''. (C99 {{M_E}})

<constant>fl-1/e</constant>

Bound to 1/''e''. (C99 {{M_E}})

<constant>fl-e-2</constant>

Bound to ''e''^2.

<constant>fl-e-pi/4</constant>

Bound to ''e''^(π/4).

<constant>fl-log2-e</constant>

Bound to log2(''e''). (C99 {{M_LOG2E}})

<constant>fl-log10-e</constant>

Bound to log10(''e''). (C99 {{M_LOG10E}})

<constant>fl-log-2</constant>

Bound to ln(2). (C99 {{M_LN2}})

<constant>fl-1/log-2</constant>

Bound to 1/ln(2). (C99 {{M_LN2}})

<constant>fl-log-3</constant>

Bound to ln(3).

<constant>fl-log-pi</constant>

Bound to ln(π).

<constant>fl-log-10</constant>

Bound to ln(10). (C99 {{M_LN10}})

<constant>fl-1/log-10</constant>

Bound to 1/ln(10). (C99 {{M_LN10}})

<constant>fl-pi</constant>

Bound to the mathematical constant π. (C99 {{M_PI}})

<constant>fl-1/pi</constant>

Bound to 1/π. (C99 {{M_1_PI}})

<constant>fl-2pi</constant>

Bound to 2π.

<constant>fl-pi/2</constant>

Bound to π/2. (C99 {{M_PI_2}})

<constant>fl-pi/4</constant>

Bound to π/4. (C99 {{M_PI_4}})

<constant>fl-pi-squared</constant>

Bound to π^2.

<constant>fl-degree</constant>

Bound to π/180, the number of radians in a degree.

<constant>fl-2/pi</constant>

Bound to 2/π. (C99 {{M_2_PI}})

<constant>fl-2/sqrt-pi</constant>

Bound to 2/√π. (C99 {{M_2_SQRTPI}})

<constant>fl-sqrt-2</constant>

Bound to √2. (C99 {{M_SQRT2}})

<constant>fl-sqrt-3</constant>

Bound to √3.

<constant>fl-sqrt-5</constant>

Bound to √5.

<constant>fl-sqrt-10</constant>

Bound to √10.

<constant>fl-1/sqrt-2</constant>

Bound to 1/√2. (C99 {{M_SQRT1_2}})

<constant>fl-cbrt-2</constant>

Bound to ∛2.

<constant>fl-cbrt-3</constant>

Bound to ∛3.

<constant>fl-4thrt-2</constant>

Bound to ∜2.

<constant>fl-phi</constant>

Bound to the mathematical constant φ.

<constant>fl-log-phi</constant>

Bound to log(φ).

<constant>fl-1/log-phi</constant>

Bound to 1/log(φ).

<constant>fl-euler</constant>

Bound to the mathematical constant γ (Euler's constant).

<constant>fl-e-euler</constant>

Bound to ''e''^γ.

<constant>fl-sin-1</constant>

Bound to sin(1).

<constant>fl-cos-1</constant>

Bound to cos(1).

<constant>fl-gamma-1/2</constant>

Bound to Γ(1/2).

<constant>fl-gamma-1/3</constant>

Bound to Γ(1/3).

<constant>fl-gamma-2/3</constant>

Bound to Γ(2/3).

==== Implementation Constants

<constant>fl-greatest</constant>

<constant>fl-least</constant>

Bound to the largest/smallest positive finite flonum. (e.g. C99 {{DBL_MAX}} and
C11 {{DBL_TRUE_MIN}})

<constant>fl-epsilon</constant>

Bound to the appropriate machine epsilon for the hardware representation of
flonums. (C99 {{DBL_EPSILON}} in {{<float.h>}})

<constant>fl-fast-fl+*</constant>

Bound to #t if {{(fl+* x y z)}} executes about as fast as, or faster than,
{{(fl+ (fl* x y) z)}}; bound to #f otherwise. (C99 {{FP_FAST_FMA}})

So that the value of this variable can be determined at compile time, R7RS
implementations and other implementations that provide a features function
should provide the feature {{fl-fast-fl+*}} if this variable is true, and not
if it is false or the value is unknown at compile time.

<constant>fl-integer-exponent-zero</constant>

Bound to whatever exact integer is returned by {{(flinteger-exponent 0.0)}}.
(C99 {{FP_ILOGB0}})

<constant>fl-integer-exponent-nan</constant>

Bound to whatever exact integer is returned by {{(flinteger-exponent +nan.0)}}.
(C99 {{FP_ILOGBNAN}})

==== Constructors

<procedure>(flonum number)</procedure>

If number is an inexact real number and there exists a flonum that is the same
(in the sense of {{=}}) to number, returns that flonum. If number is a negative
zero, an infinity, or a NaN, return its flonum equivalent. If such a flonum
does not exist, returns the nearest flonum, where "nearest" is
implementation-dependent. If number is not a real number, it is an error. If
number is exact, applies inexact or {{exact->inexact}} to number first.

<procedure>(fladjacent x y)</procedure>

Returns a flonum adjacent to {{x}} in the direction of {{y}}. Specifically: if
{{x < y}}, returns the smallest flonum larger than {{x}}; if {{x > y}}, returns
the largest flonum smaller than {{x}}; if {{x = y}}, returns {{x}}. (C99
{{nextafter}})

<procedure>(flcopysign x y)</procedure>

Returns a flonum whose magnitude is the magnitude of {{x}} and whose sign is the
sign of {{y}}. (C99 {{copysign}})

<procedure>(make-flonum x n)</procedure>

Returns {{x × 2n}}, where {{n}} is an integer with an implementation-dependent
range. (C99 {{ldexp}})

==== Accessors

<procedure>(flinteger-fraction x)</procedure>

Returns two values, the integral part of {{x}} as a flonum and the fractional
part of {{x}} as a flonum. (C99 {{modf}})

<procedure>(flexponent x)</procedure>

Returns the exponent of {{x}}. (C99 {{logb}})

<procedure>(flinteger-exponent x)</procedure>

Returns the same as flexponent truncated to an exact integer. If {{x}} is zero,
returns {{fl-integer-exponent-zero}}; if {{x}} is a NaN, returns
{{fl-integer-exponent-nan}}; if {{x}} is infinite, returns a large
implementation-dependent exact integer. (C99 {{ilogb}})

<procedure>(flnormalized-fraction-exponent x)</procedure>

Returns two values, a correctly signed fraction {{y}} whose absolute value is
between 0.5 (inclusive) and 1.0 (exclusive), and an exact integer exponent
{{n}} such that {{x = y(2^n)}}. (C99 {{frexp}})

<procedure>(flsign-bit x)</procedure>

Returns 0 for positive flonums and 1 for negative flonums and -0.0. The value
of {{(flsign-bit +nan.0)}} is implementation-dependent, reflecting the sign bit
of the underlying representation of NaNs. (C99 {{signbit}})

==== Predicates

<procedure>(flonum? obj)</procedure>

Returns #t if obj is a flonum and #f otherwise.

<procedure>(fl=? x y z ...)</procedure>
<procedure>(fl<? x y z ...)</procedure>
<procedure>(fl>? x y z ...)</procedure>
<procedure>(fl<=? x y z ...)</procedure>
<procedure>(fl>=? x y z ...)</procedure>

These procedures return {{#t}} if their arguments are (respectively): equal,
monotonically increasing, monotonically decreasing, monotonically
nondecreasing, or monotonically nonincreasing; they return {{#f}} otherwise. These
predicates must be transitive. (C99 {{=}}, {{<}}, {{>}}, {{<=}}, {{>=}}
operators respectively)

<procedure>(flunordered? x y)</procedure>

Returns {{#t}} if {{x}} and {{y}} are unordered according to IEEE rules. This
means that one of them is a NaN.

These numerical predicates test a flonum for a particular property, returning
{{#t}} or {{#f}}.

<procedure>(flinteger? x)</procedure>

Tests whether {{x}} is an integral flonum.

<procedure>(flzero? x)</procedure>

Tests whether {{x}} is zero. Beware of roundoff errors.

<procedure>(flpositive? x)</procedure>

Tests whether {{x}} is positive.

<procedure>(flnegative? x)</procedure>

Tests whether {{x}} is negative. Note that {{(flnegative? -0.0)}} must return
{{#f}}; otherwise it would lose the correspondence with {{(fl<? -0.0 0.0)}},
which is {{#f}} according to IEEE 754.

<procedure>(flodd? x)</procedure>

Tests whether the flonum {{x}} is odd. It is an error if {{x}} is not an
integer.

<procedure>(fleven? x)</procedure>

Tests whether the flonum {{x}} is even. It is an error if {{x}} is not an
integer.

<procedure>(flfinite? x)</procedure>

Tests whether the flonum {{x}} is finite. (C99 {{isfinite}})

<procedure>(flinfinite? x)</procedure>

Tests whether the flonum {{x}} is infinite. (C99 {{isinf}})

<procedure>(flnan? x)</procedure>

Tests whether the flonum {{x}} is NaN. (C99 {{isnan}})

<procedure>(flnormalized? x)</procedure>

Tests whether the flonum {{x}} is normalized. (C11 {{isnormal}}; in C99, use
{{fpclassify(x) == FP_NORMAL}})

<procedure>(fldenormalized? x)</procedure>

Tests whether the flonum {{x}} is denormalized. (C11 {{issubnormal}}; in C99,
use {{fpclassify(x) == FP_SUBNORMAL}})

==== Arithmetic

<procedure>(flmax x ...)</procedure>
<procedure>(flmin x ...)</procedure>

Return the maximum/minimum argument. If there are no arguments, these
procedures return {{-inf.0}} or {{+inf.0}} if the implementation provides these
numbers, and {{(fl- fl-greatest)}} or {{fl-greatest}} otherwise. (C99 {{fmax}}
{{fmin}})

<procedure>(fl+ x ...)</procedure>
<procedure>(fl* x ...)</procedure>

Return the flonum sum or product of their flonum arguments. (C99 {{+}} {{*}}
operators respectively)

<procedure>(fl+* x y z)</procedure>

Returns {{xy + z}} as if to infinite precision and rounded only once. The
boolean constant {{fl-fast-fl+*}} indicates whether this procedure executes
about as fast as, or faster than, a multiply and an add of flonums. (C99
{{fma}})

<procedure>(fl- x y ...)</procedure>
<procedure>(fl/ x y ...)</procedure>

With two or more arguments, these procedures return the difference or quotient
of their arguments, associating to the left. With one argument, however, they
return the additive or multiplicative inverse of their argument. (C99 {{-}}
{{/}} operators respectively)

<procedure>(flabs x)</procedure>

Returns the absolute value of {{x}}. (C99 {{fabs}})

<procedure>(flabsdiff x y)</procedure>

Returns {{|x - y|}}.

<procedure>(flposdiff x y)</procedure>

Returns the difference of {{x}} and {{y}} if it is non-negative, or zero if the
difference is negative. (C99 {{fdim}})

<procedure>(flsgn x)</procedure>

Returns {{(flcopysign 1.0 x)}}.

<procedure>(flnumerator x)</procedure>
<procedure>(fldenominator x)</procedure>

Returns the numerator/denominator of {{x}} as a flonum; the result is computed
as if {{x}} was represented as a fraction in lowest terms. The denominator is
always positive. The numerator of an infinite flonum is itself. The denominator
of an infinite or zero flonum is 1.0. The numerator and denominator of a NaN is
a NaN.

<procedure>(flfloor x)</procedure>

Returns the largest integral flonum not larger than {{x}}. (C99 {{floor}})

<procedure>(flceiling x)</procedure>

Returns the smallest integral flonum not smaller than {{x}}. (C99 {{ceil}})

<procedure>(flround x)</procedure>

Returns the closest integral flonum to {{x}}, rounding to even when {{x}}
represents a number halfway between two integers. (Not the same as C99
{{round}}, which rounds away from zero)

<procedure>(fltruncate x)</procedure>

Returns the closest integral flonum to {{x}} whose absolute value is not larger
than the absolute value of {{x}} (C99 {{trunc}})

==== Exponents and logarithms

<procedure>(flexp x)</procedure>

Returns ''e''^{{x}}. (C99 exp)

<procedure>(flexp2 x)</procedure>

Returns 2{{x}}. (C99 exp2)

<procedure>(flexp-1 x)</procedure>

Returns ''e''^{{x}} - 1, but is much more accurate than {{flexp}} for very
small values of {{x}}. It is recommended for use in algorithms where accuracy
is important. (C99 {{expm1}})

<procedure>(flsquare x)</procedure>

Returns {{x}}^2.

<procedure>(flsqrt x)</procedure>

Returns √{{x}}. For -0.0, {{flsqrt}} should return -0.0. (C99 {{sqrt}})

<procedure>(flcbrt x)</procedure>

Returns ∛{{x}}. (C99 cbrt)

<procedure>(flhypot x y)</procedure>

Returns the length of the hypotenuse of a right triangle whose sides are of
length |{{x}}| and |{{y}}|. (C99 {{hypot}})

<procedure>(flexpt x y)</procedure>

Returns {{x}}^{{y}}. If {{x}} is zero, then the result is zero. (C99 {{pow}})

<procedure>(fllog x)</procedure>

Returns ln({{x}}). (C99 {{log}})

<procedure>(fllog1+ x)</procedure>

Returns ln({{x}} + 1), but is much more accurate than fllog for values of {{x}}
near 0. It is recommended for use in algorithms where accuracy is important.
(C99 {{log1p}})

<procedure>(fllog2 x)</procedure>

Returns log2({{x}}). (C99 {{log2}})

<procedure>(fllog10 x)</procedure>

Returns log10({{x}}). (C99 {{log10}})

<procedure>(make-fllog-base x)</procedure>

Returns a procedure that calculates the base-{{x}} logarithm of its argument.
If {{x}} is 1.0 or less than 1.0, it is an error.

==== Trigonometric functions

<procedure>(flsin x)</procedure>

Returns sin({{x}}). (C99 {{sin}})

<procedure>(flcos x)</procedure>

Returns cos({{x}}). (C99 {{cos}})

<procedure>(fltan x)</procedure>

Returns tan({{x}}). (C99 {{tan}})

<procedure>(flasin x)</procedure>

Returns arcsin({{x}}). (C99 {{asin}})

<procedure>(flacos x)</procedure>

Returns arccos({{x}}). (C99 {{acos}})

<procedure>(flatan [y] x)</procedure>

Returns arctan({{x}}). (C99 {{atan}})

With two arguments, returns arctan({{y}}/{{x}}) in the range [-π,π], using the
signs of {{x}} and {{y}} to choose the correct quadrant for the result. (C99
{{atan2}})

<procedure>(flsinh x)</procedure>

Returns sinh({{x}}). (C99 {{sinh}})

<procedure>(flcosh x)</procedure>

Returns cosh({{x}}). (C99 {{cosh}})

<procedure>(fltanh x)</procedure>

Returns tanh({{x}}). (C99 {{tanh}})

<procedure>(flasinh x)</procedure>

Returns arcsinh({{x}}). (C99 {{asinh}})

<procedure>(flacosh x)</procedure>

Returns arccosh({{x}}). (C99 {{acosh}})

<procedure>(flatanh x)</procedure>

Returns arctanh({{x}}). (C99 {{atanh}})

==== Integer division

<procedure>(flquotient x y)</procedure>

Returns the quotient of {{x}}/{{y}} as an integral flonum, truncated towards zero.

<procedure>(flremainder x y)</procedure>

Returns the truncating remainder of {{x}}/{{y}} as an integral flonum.

<procedure>(flremquo x y)</procedure>

Returns two values, the rounded remainder of {{x}}/{{y}} and the low-order
{{n}} bits (as a correctly signed exact integer) of the rounded quotient. The
value of {{n}} is implementation-dependent but at least 3. This procedure can
be used to reduce the argument of the inverse trigonometric functions, while
preserving the correct quadrant or octant. (C99 {{remquo}})

==== Special functions

<procedure>(flgamma x)</procedure>

Returns Γ({{x}}), the gamma function applied to {{x}}. This is equal to
({{x}}-1)! for integers. (C99 {{tgamma}})

<procedure>(flloggamma x)</procedure>

Returns two values, log |Γ({{x}})| without internal overflow, and the sign of
Γ({{x}}) as 1.0 if it is positive and -1.0 if it is negative. (C99 {{lgamma}})

<procedure>(flfirst-bessel n x)</procedure>

Returns the {{n}}th order Bessel function of the first kind applied to {{x}},
Jn({{x}}). ({{jn}}, which is an XSI Extension of C99)

<procedure>(flsecond-bessel n x)</procedure>

Returns the {{n}}th order Bessel function of the second kind applied to {{x}},
Yn({{x}}). ({{yn}}, which is an XSI Extension of C99)

<procedure>(flerf x)</procedure>

Returns the error function erf({{x}}). (C99 {{erf}})

<procedure>(flerfc x)</procedure>

Returns the complementary error function, 1 - erf({{x}}). (C99 {{erfc}})

=== Acknowledgements

This SRFI would not have been possible without Taylor Campbell, the R6RS
editors, and the ISO C Working Group.

=== Author

John Cowan, Will Clinger

=== Maintainer

[[/users/diego-mundo|Diego A. Mundo]]

=== Repository

[[https://code.dieggsy.com/srfi-144]]

=== Copyright

 Copyright (C) John Cowan (2016). All Rights Reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in
 the Software without restriction, including without limitation the rights to
 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
 of the Software, and to permit persons to whom the Software is furnished to do
 so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE. Editor: Arthur A. Gleckler

=== Version History

; 0.1.2 : Fix tests, ensure {{flround}} behaves to spec
; 0.1.1 : More idiomatic error messages, ensure correctness of {{fl-fast-fl+*}} value/feature
; 0.1.0 : Ported to CHICKEN 5