208: NaN procedures208: NaN proceduresby Emmanuel Medernach (design), John Cowan (editor), Wolfgang Corcoran-Mathe (implementation)
This SRFI is currently in final status. Here is an explanation of each status that a SRFI can hold. To provide input on this SRFI, please send email to srfi-208@nospamsrfi.schemers.org. To subscribe to the list, follow these instructions. You can access previous messages via the mailing list archive.
This SRFI provides procedures that dissect NaN (Not a Number) inexact values.
IEEE 754:2008 is a standard for floating point numbers used on
essentially all modern CPUs that have hardware floating point support.
It specifies a set of floating-point values known as NaNs,
standing for Not A Number.
They are generated by such operations as (/ 0.0 0.0),
the mathematical result of which
could be any number whatsoever, and by (flsqrt -1.0) from
SRFI 144, the result of which cannot be any floating-point number.
Scheme implementations that conform to R6RS or R7RS use the external representations
+nan.0 and -nan.0 for NaNs,
and the procedure nan? will return #t
when applied to any inexact real number (on R7RS systems, any inexact number)
that is a NaN.
In fact, however, there are 252 - 1 possible NaN values, assuming the representation is an IEEE binary64 float. This SRFI makes it possible to dissect a NaN to see which of these internal representations it corresponds to.
If a Scheme implementation supports both this SRFI and R7RS, and
provides the Appendix B feature flag ieee-float, then the procedures of this
SRFI must conform to the semantics of IEEE 754:2008.
If a Scheme implementation does not support IEEE 754:2008,
this SRFI recommends (but does not require) that it make
no attempt to support this SRFI either, or in the alternative
to provide the procedures but cause all of them to signal
an error.
Abstractly considered, a NaN is made up of three fields: a 1-bit sign field, a 1-bit quiet/signaling bit, and a payload whose number of bits depends on the internal representation of the NaN. The difference between quiet and signaling NaNs is that quiet NaNs are passed through floating-point operations, whereas signaling NaNs may signal a hardware exception, depending on how the CPU's floating-point instructions have been configured.
It is an error to call these procedures on any object that does not satisfy
both nan? and real?,
as
demons may fly out of your nose if you try.
(make-nan negative? quiet? payload [float])
Returns a NaN whose sign bit is equal to negative?
(#t for negative, #f for positive),
whose quiet bit is equal to quiet?
(#t for quiet, #f for signaling),
and whose payload is the positive exact integer payload.
It is an error if payload is larger than a NaN can hold.
If the optional argument float is provided, it is an error if it is not an inexact real number. The NaN is represented using the same number of bits as float. The default value is 0.0. This allows Scheme implementations with multiple precisions for inexact real numbers to generate a NaN with any available precision.
(nan-negative? nan)
Returns #t if the sign bit of nan is 1 and #f otherwise.
(nan-quiet? nan)
Returns #t if nan is a quiet NaN.
(nan-payload nan)
Returns the payload bits of nan as a positive exact integer.
(nan=? nan1 nan2)
Returns #t if nan1 and nan2 have the same sign, quiet bit,
and payload; and #f otherwise.
If nan1 and nan2 are of different precisions,
they are converted to a precision at least as high as the higher-precision value
in an implementation-defined way.
The sample implementation appears in the repository
(Github)
of this SRFI.
The implementation has a C component that does the work
and a Chibi interface to it. For use on other Schemes,
the Chibi code will need to be replaced with appropriate
native code, as FFIs are not portable.
The C implementation provides code for the C types
double and float.
Most Schemes use only doubles and can ignore the
float functions. The known exceptions as of
December 2020 are Racket BC, NexJ, and Kawa.
The C implementation depends on a union type with two members,
a double (or float) and
uint64_t (or uint32_t).
On systems that use opposite endianness
for floating-point and integer numbers,
or that produce atypical results from storing one type in a union
and retrieving another type (which is implementation-defined behavior),
this implementation will not work without changes.
A study of the question produced no implementation techniques that are
more portable, so the decision was made to proceed with an imperfect
implementation rather than throwing out the baby with the bathwater.
Thanks to the participants in the SRFI mailing list.
© 2020 Emmanuel Medernach, John Cowan, Wolfgang Corcoran-Mathe.
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 (including the next paragraph) 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.