by 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.

- Received: 2020-08-26
- Draft #1 published: 2020-08-28
- Draft #2 published: 2020-11-18
- Draft #3 published: 2020-12-27
- Draft #4 published: 2021-02-22
- Finalized: 2021-02-23

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 2^{52} - 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.

Editor: Arthur A. Gleckler