## Title

NaN procedures

## Author

Emmanuel Medernach (design), John Cowan (editor), Wolfgang Corcoran-Mathe (implementation)

## Status

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

## Abstract

This SRFI provides procedures that dissect NaN (Not a Number) inexact values.

## Rationale

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.

## Specification

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.

### Procedures

`(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.

## Implementation

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.

## Acknowledgements

Thanks to the participants in the SRFI mailing list.

## Copyright

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